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CHAPTER 1 


SIDEWINDER FORCE FEEDBACK 
OVERVIEW 


About SW Force Feedback 


This chapter provides background information on force feedback and the different force effects associated 
| with this technology. SideWinder® Force Feedback, hereafter referred to as SWForee, is a force feedback 
technology that utilizes the DirectInput Force Feedback API. 


Starting with a comparison of the audio synthesis to effects synthesis, subsequent sections cover subjects 
such as: 


e The different types of effects 

¢ Position dependent and position independent effects 
e Waveform effects 

e Behavioral effects 

e Device specific effects 

e Envelope objects 

e Force direction 

e SideWinder device effects 


Comparing Audio and Force Synthesis 


Because of the similarity between the physical characteristics of audio waves and of the different forces that 
are sent to the force feedback device, the force effect system can be compared to an audio synthesizer. 
Audio is generated either by playing back digitally-sampled waveforms or by a synthesizing system that 
uses a bank of oscillators (waveform generators), filters, and modulators. This model can be applied to the 

i SWForce system in that force effects can be created through combinations of different types of force 
amplitudes and wave shapes. The following sections “Synthesizing Audio Signals” and “Synthesizing 
Force Effects” provide more details. 


Synthesizing Audio Signals 


To illustrate the audio synthesis concept, the following diagram shows how the original sound (audio) 
synthesizer that was developed some 25 years ago created an audio signal by combining (summing) signals 
from different types of oscillators. (For simplicity, the amplitude controls that allow the different audio 
waveforms to be combined at different amplitudes are not shown in the diagram.) 


SideWinder Force Feedback Overview 
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Basic Blocks of Audio Synthesizer 


In the audio synthesizer, the output of the different oscillators is gated by an Envelope Generator to a 
summing node. The summed audio signals are then filtered to generate the synthesized sound. For 
example, a flute may be synthesized by means of a sine wave oscillator. In the following diagram, a typical 
envelope generator provides the attack, sustain, and delay characteristics of the synthesized sound. 


Envelope Generator Output 


|— T1 ——}-12--—_—____——-13 —_—____—-Ta —— 
T1= Attack 

T2= Decay 

T3= Sustain 

T4= Release 


The amplitude of the sine-wave oscillator output is controlled by the envelope. For more information, see 
“The Envelope Object” in this chapter. The oscillator output is then gated through to the filter to produce the 
actual sound. The synthesized trumpet signal would then have the characteristics of the signal shown in the 
following diagram. 
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Synthesized Trumpet Waveform 


11} 12 —____++—_ 3 _| 
Ti = Attack 


T2 = Sustain 
T3 = Decay 


Synthesizing Force Effects 
Using the audio synthesizer as an analogy, waveforms and effects that correspond to forces can be 
generated. In this paradigm, effects consist of modeled varying forces that are sent to axis coordinates of 


the force feedback device (the joystick, in this case). The following illustration shows this new force 
synthesizer model, which is remarkably similar to the audio synthesizer model. 
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The Force Synthesizer 


While the audio synthesizer uses oscillators to generate waveform components, the force synthesizer uses 
software routines to create the different force model components or effects. For example, the force 
synthesizer can generate an effect similar to the vibration of a machine gun by using a square wave force 
model. The following illustration shows what the machine gun effect may look like when applied to a force 
feedback device, such as a joystick. As in the case of the audio synthesizer, we may shape the final 
waveform by means of an envelope. 


For simplicity, the traditional ADSR (attack, decay, sustain, and release) envelope is modified to the attack, 
sustain, and decay. Additionally, the envelope shape is applied to a bipolar signal that oscillates around a 
zero force baseline. 


SideWinder Force Feedback Overview 
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Ti = Attack 
T2 = Sustain 
T3 = Decay 


Concatenating Effects 


An application can concatenate effects to create even more interesting force sensations. As indicated in the 
following illustration, concatenating effects creates a new effect E,,.,, by appending a second effect E, to the 
first one E,. 


E,.w = E; followed by E, 


Concatenated Effects 


AUT I 


SUIS 
<M 


The individual Envelopes in E, and E, are preserved. E,,,, does not have a separate envelope. 


The concatenated effect is created using the Visual Force Factory tool to generate the FRC (*.frc) files. 


Superimposing Effects 


Superimposing effects creates a new effect E,,., by mixing (adding algebraically) a second effect E, to the 
first one E; on a sample-by-sample basis, as indicated in the following illustration. Superimposing assumes 
that each effect has the same number of output samples in its effect objects. 


Enew = Ej (t) + E, (t)) + E, ()) + E,(t)+...E, (+ E,() 


SideWinder Force Feedback Overview 


Superimposed Effects 
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Superimposing is performed when the effects are played back using the Start method, or by using FRC files 
generated by Visual Force Factory tool. 


Refer to Chapter 3 for information regarding the Start method. 


Force Effect Types 


An application interfaces to the force feedback device using the force feedback system, which consists of 
the DirectInput device object and the DirectInput effect objects. Applications must create effect objects 
with the different types of effects prior to using them. At the highest level, there are two basic types of 
effects that are supported by DirectInput: waveform and behavioral. As shown in the following illustration 
and described in more detail in subsequent sections, each of the categories contains several specific types of 
force effects, any of which can be combined to form more complex effects. 


A third category of force effects, which includes both waveform and behavioral types of effects, is referred 
to as device-dependent. In the case of the SideWinder Force Feedback Pro, device-dependent effects 
include ROM effects, raw force effects, wall effects, and VFXEffects. 


SideWinder Force Feedback Overview 


FORCE EFFECT TYPES 
Waveform Effects Behavioral Effects Device-Dependemnt Effects 
(SideVVinder Force Feedback Pro} 
Synthesized Spring 
Waveform 
Periodic Damper 
Friction ROM 
Sine Inertial RawF orce 
Square 
Triangle Behavioral 
Sawtooth Ee 
Non-periodic 
Complex 
L Constant force [ 
Ramp VFX 


Custom (user-defined) 


Force Effect Classes 


The dozen or so effect types listed in the previous section can be further classified with regard to their 
dependence or independence on the current position of the force feedback device. Effects that are not 
position dependent are referred to as open loop while those that are position dependent are referred to as 
closed loop. The following diagram shows which effect types are position independent and operate in open 
loop and also which are position dependent and operate in closed loop. 


FORCE EFFECT CLASSES 
Position independent Position Dependent 
{Open Loop) (Clased Loop) 
Periodic Non-periodic Device Dependent Behavioral Effects 
; (SideWinder) : 

Sine Constant force Spring 
Square ‘- Ramp L Row Damper 
Triangle Cusiom (user-defined) RawF orce Friction 

Sawtooth Inertial 


Vall 


Position independent effect objects operate in an open loop in that they do not sense the position of the force 
feedback device. The position independent effect object is a "fire and forget" kind of effect where the 
application starts the effect and can then return to other tasks. 


In contrast, position dependent effect objects operate in a closed loop mode to monitor the current position 
of the force feedback device and adjust accordingly to accurately simulate a force behavior. That is, 
application software reads force feedback device positional information and modifies the effects so that they 
are appropriate to the current position of the device. 


Closed loop operation requires a higher loop control bandwidth, on the order of 500 to 1000 position reports 
per second. Current I/O devices, such as the serial port, as well as CPU computation speed, limit the 
practicality of closed loop control with high fidelity. However, if a force feedback device implements these 
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behavioral forces as built-in effects, the device itself is responsible for closed loop servo control and not the 
application. SideWinder force feedback devices perform closed loop effect operations within the device, 
freeing the application from the task of performing computation-intensive force feedback monitoring and 
modification tasks. 


Waveform Effects 


Waveform effects are normally predefined effects that are tied to specific events during play. For example, 
the movement associated with a hit from the blast of a laser is created by a waveform effect. Waveform 
effects have predefined durations and may be modified by an envelope object. Waveform effects are time- 
dependent. 


Waveform effects include: 
e Synthesized effects 
e Custom effects 


Synthesized effects include both periodic effects (such as sine, square, triangle, and sawtooth) and non- 
period effects (such as ramp and constant force effects) 


Custom effects are normally, but not necessarily, defined by the application. These effects may also be 
referred to as sampled or digitized effects. 


Synthesized Effects 


Synthesized effects include both periodic and non-periodic effects. As indicated in the following 
illustration, periodic effects are derived from waveforms that have a defined period. These synthesized 
effects are generated by means of a specific algorithm and include: 


e Sine 

e Square 

e Triangle 

e Sawtooth Up 
e Sawtooth Down 


Non-periodic effects include: 


e constant force effect 
e ramp effect 
Each of these effects is derived from the above periodic types. A constant force effect has no defined period 


and the sustaining magnitude of the effect is constant. A ramp effect, which also has no defined period, is 
half a cycle of a triangle waveform that increases or decreases linearly over time. 
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As indicated in the above diagram, the synthesized waveforms are passed via a summing node and filter to 
create the resultant effects. 


Summing Node 


Effect 


ell 


Synthesized Wave forms 


Synthesized effects may be combined, by either concatenating or superimposing them, to generate a wide 
variety of effects. 


Synthesized effects are described by the DIPERIODIC, DIRAMPFORCE, and DICONSTANTFORCE 
structures in the DirectInput Force Feedback API. 


Custom (User-defined) Effects 


Custom or user-defined waveform effects consist of a list of forces generated with the Visual Force 
Feedback tool supplied with this SDK. Use the Visual Force Feedback tool to define and shape force 
effects. 


Custom waveform effects are described by the DICUSTOMFORCE structure in the DirectInput Force 
Feedback API. 


Force strength variation between different devices is compensated with the dwGain member in the 
DIEFFECT structure (refer to Chapter 4). The dwGain range is 1 to 10000% with the default value set to 
10000%. If attenuation is desired, reduce the dwGain value appropriately. 


The Envelope Object 


An envelope object encapsulates the synthesized waveform used in an effect and SWForce is compatible 
with the DirectInput force feedback definition of an envelope. 


Envelope objects are time-based, consisting of an initial attack, a sustain, and a fade time, each expressed in 
microseconds. In addition, each envelope includes a start amplitude, a sustain amplitude, and a final fade 
amplitude. 


Envelopes are only valid for periodic, constant force, ramp, and ROM-based effects. The attack and delay 
elements of the envelope is set in the DIENVELOPE structure. The sustain time is the duration of the 
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effect, minus the attack and fade times. The sustain amplitude is the magnitude of the specific effect type. 
For more information, see Chapter 4, “SWForce SDK Force Feedback Data Structures”. 


The following diagram illustrates how a waveform is modified by its time-based envelope to define its 
attack, sustain, and decay times. 


Time Based Envelope 
Initial Attack Amplitude 


Sustain Amplitude 


tn 
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T1 = Attack 
T2 = Sustain 
T3 = Decay 


Tl + T2 + T3 = Total duration of the effect. 


The duration of the effect is defined in the DIEFFECT data structure member as dwDuration. Members in 
the DIENVELOPE data structure define the following: 


¢ Initial attack level: The amplitude at which to start the time-based envelope. 


e Attack time: The time, in microseconds, from the start of the effect until the forces reach the sustained 
amplitude. 


¢ Total duration time: The time, in microseconds, that the effect is played This is the dwDuration 
member in DIEFFECT. The sustain time T2 is derived from T1, T3, and dwDuration. 


e Fade time: The time, in microseconds, that the effect takes to fall from the sustained amplitude to the 
Fade level amplitude. 


e Fade level: The amplitude at which the time-based envelope ends. 


Refer also to Appendix E, SWForce Waveforms, Envelopes, and Offsets for additional information on 
envelopes. 


Force Direction 


Waveform effects consist of force vectors, with amplitude and duration determined by the associated 
envelope (except in the case of user-defined effects). Direction is the final component required to output the 
effect to the force feedback device. The following direction types are possible: 


Single Axis Direction 


A force effect for a single axis device will not include direction information. In this case, the effect is 
simply sent and played to the single axis of the device. 
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Multiple Axis Direction 


Multiple axis direction uses more than one axis. For example, a force effect for a multiple axis direction can 
include the x- and y-axis in combination, or the x-, y-, and z-axis in combination. Multiple axis direction 
includes both two-degree-of-freedom (2DOF) and three-degree-of-freedom (3DOF) operation. 


DirectInput Force Feedback supports the following coordinate modes for describing direction: 


e Cartesian 

e Polar 

e Spherical 

In most cases, the force feedback device is a 2DOF device, so either Cartesian or Polar coordinates are used. 


The DIEFFECT structure members cAxes, rgdwAxes, and rglDirection describe the direction to which the 
forces are to be applied. Refer to Chapter 4 for information on the DIEFFECT structure. 


A 2DOF device is represented as two related axes, such as the x- and y-axes in a joystick. The following 
diagram illustrates how direction is implemented for an effect in the case of a joystick. In Polar coordinate 
mode, the first entry in the rgIDirection array of the DIEFFECT structure (one of the structures that 
contain effect data) contains the value of the angle, in the range of 0 to 35900 degrees from the y-axis, for 
the resultant force. 


The X-axis is negative at 270 degrees and positive at 90 degrees. The Y-axis is negative at 0 degrees and 
positive at 180 degrees. 


Top View of Computer Monitor 


North 0 Degrees 


Force from 45 Degrees 
DirectionAngle2D = 45 


West 270 Degrees 


South 180 Degrees 


Top View of FF Joystick and Force Orientation for 2 DOF 


Behavioral Effects 


Behavioral effects, also called conditions or condition effects, are defined by physical properties and are a 
function of user motion. Behavioral effects are most often background effects and are not generally 
associated with a sudden event. They are more of an environmental feel or condition, such as the change in 
the feel of an airplane as it leaves the ground. Behavioral effects are position-dependent. Behavioral effect 
objects do not have an associated envelope because they are either on or off. 
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Behavioral effects include: 


e Springs 

e Dampers 

e Inertial (Gravity and Acceleration) 

e Friction 

¢ Wall effects are also behavioral, but are specific to the SideWinder force feedback joystick. 


The DirectInput force feedback system defines behavioral, or DICONDITION, effects using the following 
parameters: 


¢ Offset: The offset from baseline of 0 force. 


¢ Positive Coefficient: The coefficient (spring, damper, inertia, friction) for the positive portion from 
the center of the axis. 


¢ Negative Coefficient: The coefficient (spring, damper, inertia, friction) for the negative portion of the 
axis. 


¢ Positive Saturation: The maximum positive force output. 
¢ Negative Saturation: The maximum negative force output. 
¢ Deadband: The region around the offset where the condition is not active. 


SWForce supports a simplified bi-directional DICONDITION effect. In this effect, the positive and 
negative coefficients are equal. In addition, the positive saturation is set to +10000% and negative 
saturation to -10000%. 


Behavioral effects can be played back concurrently with other behavioral or waveform effects to achieve 
complex effects. For example, when a damper effect is played with a sine wave effect, the sine wave force 
| is affected by the damper in proportion to its force (constant) value. 


The following sections describe these DICONDITION effects. Refer to the data structure descriptions in 
| Chapter 4 for a detailed description of DICONDITION values for each type of DICONDITION effect. 


Spring Effects 


Linear forces obey first degree physical equations. A spring force model uses the equation (Hookes Law): 
f=KxX 


where K is the spring constant and X is the spring length as it is compressed. In the SWForce 
implementation, this equations translates to: 


f=K x (X — X,) where X is the current position and _X, is the spring center. 


Refer also to the following illustration. 


: ~+— Axis 
a 
Axis Center 


The force increases as the spring is compressed. A spring’s center origin can be established at any point 
along the spring axis. The K coefficient may be positive or negative, having a valid range of -10000 to 
+10000. 
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Damper Effects 


Damper effects obey second degree physical equations and have the property that the force is dependent 
upon the velocity vector. For example, as the joystick is moved faster (dx/dt), then the forces are increased, 


while moving it more slowly decreases the forces. The damper effect is characterized by the following 
equation: 


f=Bx dx/dt+V, 


where B is a damping constant, dx/dt is the velocity vector, and Vp is the initial velocity. The B coefficient 
may be positive or negative, having a valid range of -10000 to +10000. 


In the SWForce implementation, this equations translates to: 
f= B x (v—v, ) where v is the current position and vy, is the initial velocity. 


Note: The damper force effect is typically used to simulate muddy or slushy terrain textures. 


Inertial (Gravity and Acceleration) Effects 


Inertial or gravitational forces obey third degree physical equations and have the property that the force is 
dependent upon the acceleration vector. The use of inertial effects requires a high bandwidth in order to 
have an acceptable force feedback fidelity. Force feedback devices can implement this effect in the device 
where servo loop control affords sufficient bandwidth and response. 


Inertial effects are characterized by the following equation: 
f= Mx d’x/dt + Ay 


where M is mass of the object (constant) and d’x/dt is the acceleration vector, and Ag is initial acceleration. 
M has a valid range of -10000 to 10000. 


In the SWForce implementation, this equations translates to: 


f= M x (a—a, ) where a is the current position and a, is the initial acceleration. 


Friction Effects 


Friction effects are characterized by the following equation: 
f = px 


where is the friction coefficient for the object (constant). Valid p values are in the range of -10000 to 
10000. 


Note: The effects information provided in the following sections (titled with inverse 
headings) pertain only to the SideWinder Force Feedback Pro joystick and may not be 
supported by other force feedback devices. 


Device-Dependent (Side Winder-specific) Effects a 


Device-dependent effects are unique to and supported by a specific force feedback device. At present, 
Side Winder-specific effects, unique to the SideWinder force feedback joystick, include: 


e ROM-based effects (a type of waveform effect) 
¢ RawForce effects (a type of waveform effect) 
e Wall effects (a type of behavioral effect) | 
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e VFXEffect effects (a type of complex effect) 


Note: Future versions of force feedback devices will include additional new effects. 


Complex effects are combinations of effects. You can both concatenate and superimpose effects to produce 
new effects. The SideWinder-specific VFXEffect effect is a complex effect, though it can contain one or 
more individual effects. Refer to “Concatenating Effects” and “Superimposing Effects” later in this chapter 
for more information. 

ROM Effects are a waveform effect, similar to synthesized effects, and share the same capabilities, 
including envelope control. The synthesis algorithm is built into the SideWinder force feedback joystick. 
Use the SWForce library function SWFF_CreateROMEffect to create ROM effects. The following table 


lists the available ROM effects with their GUIDs and duration values. The name of an equivalent force file 
allows you to examine the effect with the Visual Force Factory tool included with this SDK. 


For additional information, refer to “Creating Built-in ROM Effects” in Chapter 2. 


Default Duration Equivalent File 

GUID for the Effect (milliseconds) (in Forcelib folder) 
GUID_RandomNoise 12289 [ none ] 
GUID_AircraftCarrierTakeOff 2625 TakeOff3.FRC 
GUID_BasketballDribble 166 Dribblel.FRC 
GUID_CarEngineldle 10000 Car3.FRC 
GUID_Chainsawldle 1000 Chainsaw.FRC 
GUID_ChainsawInAction 1000 CSawing2.FRC 
GUID_DieselEngineldle 10000 Idling FRC 
GUID_Jump 348 Jump.FRC 
GUID_Land 250 Land1.FRC 
GUID_MachineGun 1000 MachineG.FRC 
GUID_Punched 83 Punched1.FRC 
GUID_RocketLaunch 1000 Rocketl.FRC 
GUID_SecretDoor 500 SecDoor2.FRC 
GUID_SwitchClick 25 Click2.FRC 
GUID_WindGust 500 WindGust.FRC 
GUID_WindShear 2500 WSheer2.FRC 
GUID_Pistol 50 Pistol.FRC 
GUID_Shotgun 295 Shotgun2.FRC 
GUID_Laser1 1000 Laserl.FRC 
GUID_Laser2 1000 Laser4.FRC 
GUID_Laser3 1000 Laser2.FRC 
GUID_Laser4 1000 Laser5.FRC 
GUID_Laser5 1000 Laser3.FRC 
GUID_Laser6 1000 Laser6.FRC 
GUID_OutOfAmmo 25 AmmoOut.FRC 
GUID_LightningGun 1000 Lightnng.FRC 
GUID_Missile 250 Missile.FRC 
GUID_GatlingGun 1000 Gatling. FRC 


GUID_ShortPlasma 250 Plasmal.FRC 
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GUID_xxxx Default Gain Default Duration _ Filename (Forcelib folder) 
PlasmaCannon1 100 500 Plasma2.FRC 
PlasmaCannon2 99 625 Plasma3.FRC 
Cannon 100 440 Cannon.FRC 


RawForce Effects 


The RawForce effect is a special case effect. Normally, DirectInput will download an effect when it is 
created, taking up RAM space in the device. Games will typically have forces already computed from the 
physics engine, and will simply want to send the forces (Raw) to the device. A GUID_RawForce effect will 
accomplish this without taking out valuable RAM space. The only restriction is that only the last modified 
or created GUID_RawForce effect can be active. This effect may be created using the SWForce library 
function SWFF_CreateRawForceEffect. The force magnitude is modified by a SetParameter which will 
cause the force to be sent to the device directly. The library function SWFF_PutRawForce will perform this 
same function. Since this is a “raw force” output, SWFF_PutRawForce ignores the gain, duration, and other 
DIEFFECT member parameters. 


You can create what are called Dynamic effects or sensations with the GUID_RawForce effect. 


Wall Effects 


Wall effects have a wall constant, a wall angle, and a wall distance as indicated in the diagram below. 
Although the diagram illustrates a wall at 45 degrees, SWForce only supports North (0 degrees), East (90 


degrees), South (180 degrees) and West (270 degrees) walls. Refer to BE_WALL_PARAM in Chapter 4 
for additional information. | 


‘Wall Constant 


Wail Angle 


Wall Distance 


Joystick Center 


SWForce will support up to four separate wall effects. Each effect can be oriented in 0, 90, 180, or 270 
degrees. Using DirectInput Force Feedback’s range, they correspond to 0, 9000, 18000, and 27000. The 
SWForce library function SWFF_CreateWallEffect may be used to create this effect type. 


VFXEffect Effects | 


This type of effect is created by first using the Visual Force Factory tool and saving the effect(s) to an FRC 
file. The effect, described in the VFX_PARAM structure, is then implemented as a GUID_VFXEffect effect 
with several SW_CreateVFXEffectFromXXX helper functions contained in the SWForce library described 
in Appendix E. 


Currently, VFXEffect parameter modification is only valid for the duration, gain, direction, and button 


playback. For complex effects containing more than one atomic effect, modification of duration, gain, and 
direction is done by scaling. 
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Note: When the effect is first created, the button playback member is ignored. 


SideWinder Force Feedback Device Specifications 


The Side Winder Force Feedback joystick can support all of the base DirectInput force feedback effects. 

The SideWinder Force Feedback joystick has a limited amount of RAM available for downloaded effects. 
The following table lists the number of force effects that can be supported concurrently. Refer to Chapter 4, 
SWForce SDK Force Feedback Data Structures for detailed description of the DIEFFECT structure and the 


type specific parameters. 
Waveform Effects | Max. Quantity [Comments 
Up to 10 combo 
Tip: To achieve longer durations, you can 


GUID_ConstantForce 
4 
trade resolution for duration. 


GUID_RampForce 
GUID_Square 
GUID_Sine 
GUID_Triangle 
GUID_SawtoothUp 
GUID_RawForce Does not take up any memory slot 
Built-in ROM Effect 4 GUID_Laser, for example. There are 32 pre- 
defined ROM effects. 
Behavioral Effects | Max. Quantity _ | Comments 
North, West, South, and East 


Limited to 100 bytes per waveform. Data 
compression is used to vary the actual 
duration. 


GUID_SawtoothDown 
GUID_CustomForce 
GUID_Inertia 
GUID_Friction 
GUID_Wall 
Device-Dependent 


GUID_VFXEffect 


Up to eight atomic effects in the effect. Note: 
If delays are introduced between atomic 
effects, the delay object counts as one of the 
eight atomic effects. 


Additionally, up to 16 effects can play simultaneously and SideWinder allows a maximum of 32 
downloaded effects at any given time. 


Differences between DirectInput Force and SWForce Effects 


IDirectInputEffect::Start( ) - The Start method only supports an iteration count of one. 


DICONDITION - SWForce effects do not support saturation and deadband. SWForce effects only support 
the positive coefficient member in the structure. 
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DIPERIODIC - SWForce effects do not support all phase values. Only phase values 0, 9000, 18000 are 
valid. 


Note: In Visual Force Factory, cosine and square up/down are created using standard DirectInput force | 
feedback effects with phase values of 9000 and 18000. For example, cosine is a GUID_Sine with a phase of 
90 degrees (value = 9000). , 


DICUSTOMFORCE - SWForce supports single channel data arrays. 
DIENVELOPE - SWForce fully supports DirectInput force feedback envelopes. 


Some of the Directinput effect parameters may not be available for all SWForce effects. The following 
table outlines the parameters that may be modified at create and modify time, or at create time only. The 
listed DIEP_ flags are passed as parameters in the IDirectInputEffect::SetParameters method. 


Constant | Ramp Periodic { Condition | Custom | Wall VFX 
Force Force Effect Force Effect Effect 


DIEP_DURATION Create Create 1 Create Create Create Create Create 4 Create 7 
Modify Modify 1 Modify Modify Modify Modify Modify 4 Modify 7 
DIEP_SAMPLEPERIOD Create Create Create Create 5 
Modify Modify Modify Modify 5 
DIEP_GAIN Create Create Create Create Create 6 Create 8 
Modify Modify Modify Modify Modify 6 Modify 8 
DIEP_TRIGGERBUTTON Create Create Create Create Create Create Create Modify 
Modify Modify Modify Modify Modify Modify Modify 
DIEP_TRIGGERBUTTON 
REPEATINTERVAL 
DIEP_DIRECTION Create Create Create Create Create Create 9 Create 
Modify Modify Modify Modify Modify Modify 9 Modify 
DIEP_ENVELOPE Create Create Create Create 
: Modify Modify Modify Modify 
DIEP_TYPESPECIFIC Create Create Create Create Create Create Create Create 
PARAMETERS Modify Modify 2 Modify 3 Modify Modify Modify 


1 Ramp does not support infinite duration. 


2 Once a Ramp is created, like. Ramp_Up, it cannot be modified to become a Ramp_Down. For example,. once the effect is 
created with DIRAMPFORCE. Start > DIRAMPFORCE.IEn4d, it cannot be changed to DIRAMPFORCE. Start < 
DIRAMPFORCE.lEnd. 


3 Phase cannot be modified after a Periodic effect has been created. 

4 DEFAULT_ROM_EFFECT_DURATION indicates use the ROM effect recipe for duration. 

5 DEFAULT_ROM_EFFECT_OUTPUTRATE indicates use the ROM effect recipe for Output Rate. 

6 DEFAULT_ROM_EFFECT_GAIN indicates use the ROM effect recipe for gain. | 
7 DEFAULT_VFX_EFFECT_DURATION indicates use the VFX effect setting for duration. 

8 DEFAULT_VFX_EFFECT_GAIN indicates use the VFX effect setting for gain. 

‘9 DEFAULT_VFX_EFFECT_DIRECTION indicates use the VFX effect setting for direction. | 
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CHAPTER 2 


SWFORCE PROGRAMMING MODEL 


Introduction 


This chapter provides background information on the SWForce force feedback programming model. 
SWForce uses the DirectInput component in DirectX™ 5 as the data storage and transfer layer for force 
effects from the host application to the force feedback device. Starting with a brief description of the 
DirectInput Force Feedback Programming model, subsequent sections cover such topics as: 


¢ The DirectInputDevice2 and DirectInputEffect interfaces 
e SWForce function library 

e Opening the default force feedback device 

e Creating effects 


e Playing back effects 


DirectInput Force Feedback 


The SWForce feedback subsystem utilizes the force feedback COM interfaces implemented in the 
DirectInput component in DirectX™ 5. The client application creates the DirectInputDevice object for a 
force feedback device and subsequently uses the CreateEffect method, provided by the 
IDirectInputDevice2 interface, to create DirectInputEffect objects (effects). 


The client application creates an instance of a force feedback device (DirectInputDevice) object and 
initializes it to the hardware device driver, such as for a force feedback joystick. Once a force feedback 
device object is created, the client application calls its CreateEffect method to create DirectInputEffect 
objects. DirectInputEffect objects can then be played back to the force feedback device by the client 
application. 
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The IDirectInputDevice2 Interface 


The DirectInputDevice COM object inherits the three methods of the [Unknown interface: 
QuerylInterface, AddRef, and Release. 


The IDirectInputDevice2 interface includes the following methods for directly accessing the 
DirectInputDevice force feedback device. This section describes only the methods related to force feedback 
devices. 


General Methods 


IDirectInputDevice2::GetCapabilities - returns information for the specified force feedback device. 


IDirectInputDevice2::GetDevicelInfo - returns information about an instance of the specified force 
feedback device. 


IDirectInputDevice2::GetEffectInfo - obtains information about a particular effect. 


IDirectInputDevice2::CreateEffect - creates and initializes and instance of an effect and returns a pointer 
to its IDirectInputEffect interface. 


IDirectInputDevice2::SendForceFeedbackCommand - sends specific commands to the force feedback 
device. 


IDirectInputDevice2::GetForceFeedbackState - returns the current state of the force feedback device. 
Enumeration Methods 


IDirectInputDevice2::EnumCreatedEffects - enumerates all [DirectInputEffect objects currently created 
for the force feedback device. 
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IDirectInputDevice2::EnumEffects - enumerates all IDirectInputEffect object types supported by the force 
feedback device. 


The IDirectInputEffect Interface 


The DirectInputEffect COM object inherits the three methods of the [Unknown interface: 
QueryInterface, AddRef and Release. 


The IDirectInputEffect interface encapsulates the following methods for directly accessing the force effect. 


Effects Methods 


IDirectInputEffect::GetE ffectStatus - returns the status for the existing effect object. 
IDirectInputEffect::GetEffectGuid - returns the GUID for the existing effect. 
IDirectInputEffect::GetParameters - returns the data structure for the existing effect object. 


IDirectInputEffect::SetParameters - sets the data structure for the existing effect object. 


Host to/from Device Methods 

IDirectInputEffect:: Download - downloads the existing effect object to the force feedback device. 
IDirectInputEffect::Unload - removes the effect from the force feedback device. 
IDirectInputEffect::Escape - send hardware-specific commands to the device driver. 
IDirectInputEffect::Start - starts playback of the downloaded effect. 

IDirectInputEffect::Stop - stops the playing of the effect. 


IVFX Visual Force Interface 


The IVFX (Visual Force) interface object includes two methods that create effects from FRC files. Effects 
created with the IVFX methods can be used with all force feedback devices. 


Note: The IVFX interface is a COM object and inherits the three methods of the IUnknown interface: 
QueryInterface, AddRef and Release. 


The IVFX interface encapsulates the following methods for creating effects from data contained in FRC 
files. 


IVFX::CreateEffectFromFile - creates an array of effects from an FRC file. 
IVFX::CreateEffectFromBuffer - creates an array of effects from a buffer that contains an FRC file. 


SideWinder Force Feedback Function Library 


The SWForce SDK includes a source code file containing functions that simplify the DirectInput complexity 
and hide the implementation details from the caller. This function library is contained in the file 
swff_lib.cpp. The prototype headers are defined in the header file sw_force.h. The following listed functions 
are referenced throughout this document and are described in Chapter 5. 
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Device 


SWFF_OpenDefaultFF Joystick 
SWFF_OpenDefaultFFJoystickEx 
SWFF_PutRawForce 
SWFF_PutRawAxisForce 
SWFF_DestroyEffect 


Effect Creation 


SWFF_CreateRawF orceEffect 
SWFF_CreateRawAxisForceEffect 
SWFF_CreateROMEffect 
SWFF_CreatePeriodicEffect 
SWFF_CreateSpringEffect 
SWFF_CreateDamperEffect 
SWFF_CreatelnertiaEffect 
SWFF_CreateFrictionEffect 
SWFF_CreateConditionEffect 
SWFF_CreateRampEffect 
SWFF_CreateConstantForceEffect 
SWFF_CreateWallEffect 
SWFF_CreateVFXEffectFromFile 
SWFF_CreateVFXEffectFromFileEx 
SWFF_CreateVFXEffectFromBuffer 


SWFF_CreateVFXEffectFromBufferEx 


SWFF_CreateDIEffectFromFile 
SWFF_CreateDIEffectFromFileEx 
SWFF_CreateDIEffectFromBuffer 
SWFF_CreateDIEffectFromBufferEx 


Effect Parameter Modification 
SWFF_SetGain 


SWFF_SetDirection 
SWFF_SetDuration 


Using the IDirectInput Force Feedback Interfaces 
A typical client application uses the IDirectInputDevice2 and IDirectInputEffect interfaces in the 


following way: 


e Creates the force feedback device DirectInputDevice object. 
e Creates private forces and effects or uses enumerated effects which are DirectInputEffect objects. 


e Commands effects to be activated. 
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¢ When the application is to be terminated, destroys the DirectInputEffect objects and then the 
DirectInputDevice object. 


Opening the Default Force Feedback Device 


The first step, before utilizing any of the IDirectInputDevice2 methods, is to obtain an interface pointer to 
the DirectInputDevice COM object. The following example module SWFF_OpenDefaultFFJoystickEx 
illustrates how to open a force feedback device by: 


¢ Creating an instance of a DirectInputDevice object. 
e Initializing it to the default Force Feedback joystick device. 
e Returning a pointer to the DirectInputDevice object to the caller. 


// Function: SWFF_OpenDefaultFFJoystickEx 
// Parameters: IN HWND hWnd - Application Window Handle 


// LPDIRECTINPUT* ppDI - Pointer to DirectInputDevice 
// HINSTANCE hInstance - object instance handle 

// LPDIRECTINPUTDEVICE2* ppDIDevice) - Pointer to 

// IDirectInputDevice2 

// DWORD dwFlags - Cooperative level flags 

// 


// Returns: 
// Algorithm: 
// Comments: 
1 iieiaeieeiaeeteataataetaaataatatatmaamedaaeddedee ET 
HRESULT SWFF_OpenDefaultFFJoystickEx ( 
IN HWND hWnd, 
IN HINSTANCE hInstance, 
OUT LPDIRECTINPUT* ppDI, 
OUT LPDIRECTINPUTDEVICE2* ppDIDevice, 
IN DWORD dwFlags) 


HRESULT hResult; 
if (hWnd == NULL) 
{ 
return SFERR_INVALID_PARAM; 


// create the DirectInput object 
hResult = DirectInputCreate(hInstance, DIRECTINPUT_VERSION, ppDI, NULL); 
if (FAILED (hResult) ) 

return hResult; 


// enumerate the first attached joystick 

// instance goes in pDIDevicelInstance 

//DIEDFL_ATTACHEDONLY 

DIDEVICEINSTANCE DIDeviceInstance; 

hResult = (*ppDI) ->EnumDevices (DIDEVTYPE_JOYSTICK, DIEnumDevicesProc, 
&DIDeviceInstance, DIEDFL_FORCEFEEDBACK) ; 

if (FAILED (hResult) ) 

return hResult; 


// create the DirectInput Device object 
LPDIRECTINPUTDEVICE pDIDevice = NULL; 
hResult = (*ppDI) ~>CreateDevice (DIDeviceInstance.guidInstance, &pDIDevice, NULL); 
if (FAILED (hResult) 
{ 
(*ppDI) ->Release(); 
return hResult; 
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// get a pointer to its DirectInputDevice2 interface 


hResult = pDIDevice->QueryInterface (IID IDirectInputDevice2, (void**) ppDIDevice) ; 


if (FAILED (hResult) ) 

{ 
(*ppDI) ->Release(); 
pDIDevice->Release(); 
return hResult; 

} 

pDIDevice->Release(); 

pDIDevice = NULL; 


// set the data format to the pre-defined DirectInput 
// joystick format 
hResult = (*ppDIDevice) ->SetDataFormat (&c_df£DIJoystick) ; 
if (FAILED (hResult) ) 
{ 
(*ppDIDevice) ->Release(); 
(*ppDI) ->Release(); 
return hResult; 


// set the cooperative level 
hResult = (*ppDIDevice) ->SetCooperativeLevel (hWnd, dwFlags) ; 
if (FAILED (hResult) ) 
{ 
(*ppDI Device) ->Release() ; 
(*ppDI) ->Release(); 
return hResult; 


// turn auto-center off 

DIPROPDWORD DIPropAutoCenter; 

DIPropAutoCenter.diph.dwSize = sizeof (DIPropAutoCenter) ; 
DIPropAutoCenter.diph.dwHeaderSize = sizeof (DIPROPHEADER) ; 
DIPropAutoCenter.diph.dwObj = 0; 
DIPropAutoCenter.diph.dwHow = DIPH_DEVICE; 
DIPropAutoCenter.dwData = 0; 


hResult = (*ppDI Device) ->SetProperty (DIPROP_AUTOCENTER, &DIPropAutoCenter. diph) ; 


if (FAILED (hResult) ) 

{ 
(*ppDI Device) ->Release(); 
(*ppDI) ->Release(); 
return hResult; 


// acquire the joystick 
hResult = (*ppDIDevice) ->Acquire(); 
if (FAILED (hResult) ) 
{ 
(*ppDIDevice) ->Release(); 
(*ppDI) ->Release(); 
return hResult; 
} 
return SUCCESS; 
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Creating Effects 


Effect objects are created with the [DirectInputDevice2::CreateEffect method, which returns an interface 
pointer to the newly created effect object. Consequently, effect objects are "owned" by the 
DirectInputDevice object. 


The following code segment calls a SWFF_CreatePeriodicE ffect library function to create the effect object 
and obtain the IDirectEffect interface. The IDirectEffect interface has characteristics similar to that of an 
earthquake. 


#include "sw_force.h” 


1 aiieeaeeeeeteeetaeiaaade eee 
// Function: MakeEarthquake 

// Parameters: LPDIRECTINPUTDEVICE2 pDIDevice - Pointer toa 
// DirectInputDevice object 
// Comments: This effect has an envelope 

[ [warm nnn nnn nnn nn nnn nn nnn eon eo oo oe $e 


HRESULT MakeEarthquake (LPDIRECTINPUTDEVICE2 pDIDevice) 
{ 

HRESULT hResult; 

LPDIRECTINPUTEFFECT pEarthquake; 


hResult = SWFF_CreatePeriodicEffect (pDIDevice, 


épEarthquake, 

SINE, // a sine effect 
5000*1000, // duration 
HZ_TO_uS(8), // Bz 

4500, // degrees from North 
10000, // magnitude 

0, // offset 
3500000,0,250000,0, // envelope 
-1); // no button playback 


if (FAILED(hResult)) return hResult; 


// At this point, there is an initialized DirectInputEffect object 
// that is referenced by the interface pointer to the Earthquake 
// effect object 


Creating a Periodic Effect 


The following example shows a function (SWFF_CreatePeriodicEffect) that creates a generic periodic 
effect and is called by MakeEarthquake described in “Creating Effects.” The example 
SWFF_CreatePeriodicEffect function: 


e Defines the DIEFFECT structure. 

e Defines the DIENVELOPE structure 
e Defines the DIPERIODIC structure. 
® Creates the effect. 


| Micoieiaeiaateiaaienaiainiaieateteetatetatatatatatetatatanaae ene 
/ Function: SWFF_CreatePeriodicEffect 

// Purpose: Creates a Periodic type Effect with specified params 
// Parameters: LPDIRECTINPUTDEVICE2 pDIDevice - Pointer to 
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// IDirectInputDevice2 
// LPDIRECTINPUTEFFECT* ppDIEffect - Pointer to 
// DirectInputEffect* 
// DWORD dwType - Type of PERIODIC Effect 
// DWORD dwDuration - in us 
// DWORD dwPeriod - in us 
// DWORD dwDirection - in in degrees 
// DWORD dwMagnitude - in 0-10000 
// LONG lOffset - Envelope in +/-10000 
// DWORD dwAttackTime - Envelope Attack Time in uS 
// DWORD dwAttackLevel - Envelope Attack Level in 0-10000 
// DWORD dwFadeTime - Envelope Fade time in uS 
// DWORD dwFadeLevel - Envelope Fade Level 
// LONG 1Button) - index of button 
// 
// Returns: 
// Algorithm: 
// Comments: 
// The types of PERIODIC Effect are: 
// SINE, COSINE, SQUARE_HIGH, SQUARE_LOW, TRIANGLE_UP, 
//  TRIANGLE_DOWN, SAWTOOTH_UP, SAWTOOTH_DOWN, RAMP UP 
// RAMP DOWN, SPRING, INERTIA, DAMPER, FRICTION, WALL 
// 
| ieiatataietarnietabanetatatatenetatatanenetatetetatatatetatatatetetanatatataataatataataanataaamataaaeedanataaateemae 
HRESULT SWFF_CreatePeriodicEffect ( IN LPDIRECTINPUTDEVICE2 pDIDevice, 
IN OUT LPDIRECTINPUTEFFECT* ppDIEffect, 
IN DWORD dwType, 
IN DWORD dwDuration, 
IN DWORD dwPeriod, 
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// type-specific stuff 
DWORD dwPhase = 0; 
GUID guid; 
switch (dwType) 
{ 
case SINE: 
guid = GUID_Sine; 
break; 
case COSINE: 
guid = GUID Sine; 
dwPhase = 9000; 
break; 
case SQUARE HIGH: 


DWORD dwDirection, 
DWORD dwMagnitude, 
LONG 1Offset, 

DWORD dwAttackTime, 
DWORD dwAttackLevel, 
DWORD dwFadeTime, 
DWORD dwFadeLevel, 
LONG 1Button) 


guid = GUID Square; 


break; 
case SQUARE LOW: 


guid = GUID Square; 


dwPhase = 18000; 
break; 
case TRIANGLE_UP: 


guid = GUID Triangle; 


break; 
case TRIANGLE DOWN: 


guid = GUID_Triangle; 


dwPhase = 18000; 
break; 
case SAWTOOTH_UP: 
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guid = GUID _SawtoothUp; 
break; 

case SAWTOOTH DOWN: 
guid = GUID_SawtoothDown; 
break; - 

default: 
// illegal 
break; 


DIPERIODIC DIPeriodicStruct; 
DIPeriodicStruct.dwMagnitude = dwMagnitude; 
DiIPeriodicStruct.lOffset = lOffset; 
DIPeriodicStruct.dwPhase = dwPhase; 
DIPeriodicStruct.dwPeriod = dwPeriod; 


DIENVELOPE DIEnvelopeStruct; 
DIEnvelopeStruct.dwSize = sizeof (DIENVELOPE) ; 
DIEnvelopeStruct.dwAttackTime = dwAttackTime; 
DIEnvelopeStruct.dwAttackLevel = dwAttackLevel; 
DIEnvelopeStruct.dwFadeTime = dwFadeTime; 
DIEnvelopeStruct.dwFadeLevel = dwFadeLevel; 


DWORD rgdwAxes[2}; 
rgdwAxes[0} = DIJOFS_X; 
rgdwAxes[1] = DIJOFS Y; 


LONG rglDirection{[2]; 
rglDirection[0] = dwDirection; 


rglDirection[1] = 0; 


DIEFFECT DIEffectStruct; 


DIEffectStruct.dwSize = sizeof (DIEFFECT) ; 

DIEffectStruct.dwFlags = DIEFF_OBJECTOFFSETS | DIEFF_POLAR; 
DiEffectStruct.dwDuration = dwDuration; 
DIEffectStruct.dwSamplePeriod = HZ_TO_uS(100); 
DIEffectStruct.dwGain = 10000; 

DIEffectStruct.dwlriggerButton = 1Button == -1 ? DIEB_NOTRIGGER : 


FIELD_OFFSET(DIJOYSTATE, rgbButtons) + 1Button; 
DIEffectStruct.dwTriggerRepeatiInterval= 0; 
DIEffectStruct.cAxes = 2; 


DIEffectStruct.rgdwAxes = rgdwAxes; 
DIEffectStruct.rglDirection = rglDirection; 
DIEffectStruct.lpEnvelope = &DIEnvelopeStruct; 
DIEffectStruct.cbTypeSpecificParams = sizeof (DIPeriodicStruct); 
DIEffectStruct.lpvTypeSpecificParams = &DIPeriodicStruct; 


HRESULT hResult; 

hResult = pDIDevice->CreateEffect (guid, &DIEffectStruct, 
ppDIEffect, NULL); 

return hResult; 


Creating Complex Effects (GUID_VFXEffect) 


The following example shows how a complex effect may be created using the Side Winder specific effect 
GUID_VFXEffect. The Visual Force Factory tool included in this SDK will automatically generate 
GUID_VFXEffect effects that can be saved as a file with an FRC extension. This file can be automatically 
loaded as a resource by creating the GUID_VFXEffect type of effect. 


[ [mower nnn nn nnn nnn nnn nnn nnn nnn 
// Function: TestVFxXCreateFromFile 
// Parameters: 
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// Returns: 

// Algorithm: 

// Comments: 

// Note: the Effect object is released 

| 1 iieeiaaeaaeaaentastetatsaetaaadataaadaatadadaadeteet ed te 


HRESULT TestVFXCreateFromFile (LPDIRECTINPUTDEVICE2 pDIDevice) 
{ 

LPDIRECTINPUTEFFECT pLandHard; 

const TCHAR szFileName[] = {"LandHard.frc"}; 


HRESULT hResult; 
hResult = SWFF_CreateVFXEffectFromFile (pDIDevice, épLandHard, szFileName) ; 
1f (SUCCESS != hResult) return (hResult); 
return (pLandHard->Start(1,0)); 
} 


The Visual Force Factory tool will automatically generate the appropriate data structures for recreating the 
individual effects. 


Creating Built-in ROM Effects 


The Side Winder Force Feedback joystick includes built-in ROM effects for such effects as a gattling gun, 
shotgun, rocket launcher, and so on. The client application determines any built-in ROM effect capabilities 
of a device by enumerating the GUIDs for each type of built-in ROM effect. The application then accesses 
these effects by first creating them using the GUIDs. ROM effects are treated like synthesized effects and 
include envelope control. 


The Side Winder Force Feedback SDK includes a header file describing the available ROM effects that the 
device can support. The GUIDs are defined in the header file Sw_force.h 


The following example illustrates the method for creating ROM effects: 


// Function: TestROMEffect 

// Parameters: 

// Returns: 

// Algorithm: 

// Comments:Has Envelope 

// Note: the Effect object is not deleted in this test 


HRESULT TestROMEffect (LPDIRECTINPUTDEVICE2 pDIDevice) 
{ 
const unsigned cROMEffect = 32; 
static unsigned iROMEffect = 0; 
static LPDIRECTINPUTEFFECT pROMEffect = NULL; 
static GUID romGUID[CROMEffect]; 


HRESULT hResult = SUCCESS; 


1£ (++iROMEffect >= cROMEffect) 
LROMEffect = 0; 


if (pROMEffect) 

{ 
// destroy the previous effect 
hResult = pROMEffect->Release(); 
PROMEffect = NULL; 
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else 
{ 
//initialize romGuid array, since this must be the first time 
romGUID[0] = GUID_RandomNoise; 
romGUID{1}] = GUID AircraftCarrierTakeOff; 
romGUID(2] = GUID_BasketballDribble; 


romGUID[3] = GUID_CarEngineldle; 
romGUID(4] = GUID _ChainsawIdle; 
romGUID[5] = GUID_ChainsawiInAction; 


romGUID[6] = GUID DieselEngineldle; 
romGUID(7] = GUID Jump; 
romGUID[8] = GUID_Land; 
romGUID[9] = GUID _MachineGun; 
romGUID[10] = GUID_Punched; 
romGUID[11] = GUID_RocketLaunch; 
romGUID{12] = GUID_SecretDoor; 
romGUID[13] = GUID_SwitchClick; 
romGUID{14] = GUID _WindGust; 
romGUID[15] = GUID _WindShear; 
romGUID[16}] = GUID_Pistol; 
romGUID[17] = GUID_Shotgun; 
romGUID[18] = GUID_Laserl; 
romGUID{19] = GUID Laser2; 
romGUID{20] = GUID Laser3; 
romGUID[21] = GUID Laser4; 
romGUID[{22] = GUID _LaserS; 
romGUID[23] = GUID_Laser6; 
romGUID[24} = GUID_OutOfAmmo; 
romGUID[{25] = GUID_LightningGun; 
romGUID[26] = GUID_Missile; 
romGUID[27] = GUID_GatlingGun; 
romGUID[28] = GUID _ShortPlasma; 
romGUID[29] = GUID_PlasmaCannon1; 
romGUID[30] = GUID_PlasmaCannon2; 
romGUID [31] GUID_Cannon; 


wsprintf(g_szOutput, "Playing ROM Effect %d.\r\n", iROMEffect+1); 
OutputStr(g_szOutput); 


// create the effect 

GUID guid = romGUID[iROMEffect]; 

hResult = SWFF_CreateROMEffect (pDIDevice, &pROMEffect, guid, 
DEFAULT_ROM_EFFECT_DURATION, 
DEFAULT_ROM_EFFECT_GAIN, 
GO, -1}4 

if (FAILED(hResult)) return hResult; 


// start the effect 
hResult = pROMEffect->Start(1,0); 


return hResult; 


} 


The default values will cause the Side Winder device to use the pre-defined Gain and Duration appropriate 
for the built-in Effect. Entering a value other than the default will override the “recipe” for the effect and 
will change the Effect characteristics. 


Playing Back Effects 


A newly created effect can be played back to the force feedback device as follows: 


hResult = pEarthquake->Start(1, 0); // Interations=1, 
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// dwFlags = Superimposed 
if (FAILED (hResult)) return (hResult); 


// Wait until the Effect is finished playing before destroying. 
hResult = WaitUntilDone (pEarthquake) ; 
if (FAILED (hResult)) return (hResult); 
hResult = pEarthquake->Release(); 
if (FAILED (hResult)) return hResult; 


If you want to play the effect SOLO, use: 


hResult = pEarthquake->Start(1, DIES SOLO); 


Waiting While the Effect is Played 


The following example shows a function that waits until the effect is finished playing. This function is called 
by MakeEarthquake described in “Creating Effects.” 


1 locetatenetatatetenataieiatatatatatatatatataetetetetatatatatatatatedatatatatatataaaatataaanatatataetaetatetateteetete 
// Function: WaitUntilDone 
// Purpose: Sits in loop until Effect is completed. 


// Parameters: 

// Returns: 

// Algorithm: 

// Comments: 

// Note: Assumes the Effect duration is not INFINITE. 


1 atatetabeiatatatanatatniniatatatatatetatatatatetetetatatatatatatatatatensatataatatabataataaatanaataatatatatamaeteeated 
HRESULT WaitUntilDone (LPDIRECTINPUTEFFECT pDIEffect) 
{ 

HRESULT hResult = SUCCESS; 

DWORD dwFlags; 

pDIEffect->GetEffectStatus (&dwFlags) ; 

while (dwFlags & DIEGES PLAYING) 

{ 

hResult = pDIEffect->GetEffectStatus (&dwFlags); 

} 

return hResult; 
, 
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CHAPTER 3 


SWFORCE SDK FORCE FEEDBACK 
INTERFACE METHODS 


This chapter provides information on the Force Feedback specific component of DirectInput 5.0. The 
interfaces are IDirectInputDevice2 and IDirectIinputEffect. 


Note: The return code SUCCESS is defined as DI_OK, meaning the operation completed successfully. 


IDirectInputDevice2::GetCapabilities 


The GetCapabilities method returns capabilities information for the specified force feedback device. 


Syntax 


HRESULT IDirectInputDevice2::GetCapabilities/LPDIDEVCAPS Ipdc) 
IN OUT LPDIDEVCAPS Ipdc . 


Parameters 

lpde Pointer to a DIDEVCAPS data structure that describes the force feedback 
device. 

Returns 

SUCCESS Device is found. 

DIERR_INVALIDPARAM See the Appendix. 


IDirectInputDevice2::GetDeviceInfo 


The GetDeviceInfo method returns information about the instance of the specified force feedback device. 


Syntax 


HRESULT IDirectInputDevice2::GetDeviceInfo( LPDIDEVICEINSTANCE pdidi) 
OUT LPDIDEVICEINSTANCE pdidi 


Parameters 

pdidi Pointer to a DIDEVICEINSTANCE structure that is to receive the 
information about the device’s identity. The dwSize field must be initialized 
before calling this method. If dwSize is equal to the size of the 
DIDEVICEINSTANCE30 structure, then a DX3 compatible structure is 
returned instead of a DXS.0 structure. 

Returns 

SUCCESS Device is found. 


DIERR_INVALIDPARAM One or more parameters was invalid. 
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IDirectInputDevice2::SendForceFeedbackCommand 


The SendForceFeedbackCommand method sets the DirectInput force feedback device to a specified state 
by sending the appropriate command. The device must be acquired for this method to succeed. 


Syntax 


HRESULT IDirectInputDevice2::SendForceFeedbackCommand(DWORD dwFlags) 
IN DWORD  dwFlags 


Parameters 

dwFlags The command sent to the force feedback device: 
DISFFC_ACTUATORSON — Enable motors. 
DISFFC_ACTUATORSOFF — Disable motors. 
DISFFC_PAUSE— Pause playing effects. 
DISFFC_CONTINUE — Continue to play effects. 
DISFFC_STOPALL— Stop playing effects (cannot be continued; effects need to be 
explicitly restarted by the game application). 
DISFFC_RESET— Destroy all effects and disable motors. 

Returns 

SUCCESS Device found and properly set. 

DIERR_INPUTLOST See the Appendix.. 


DIERR_INVALIDPARAM 
DIERR_NOTEXCLUSIVEACQUIRED 
DIERR_UNSUPPORTED 


IDirectInputDevice2::GetForceFeedbackState 


The GetForceFeedbackState method returns the current state of the DirectInput force feedback device. The 
device must be acquired for this method to succeed. 


Syntax 


HRESULT IDirectInputDevice2::GetForceFeedbackState(LPDWORD pdwOut) 
IN LPDWORD  pdwOut 


Parameters 

PdwOut Pointer to flags that describe the current state of the force feedback device. The value 
can be a combination of the following: 
DIGFFS_ACTUATORSON — Motors enabled. 
DIGFFS_ACTUATORSOFF — Motors disabled. 
DIGFFS_POWERON — Power to motors on. 
DIGFFS_POWEROFF — Power to motors off. 
DIGFFS_SAFETYSWITCHON — Hands-on safety switch on. 
DIGFFS_SAFETYSWITCHOFF— Hands-on safety switch off. 
DIGFFS_USERFFSWITCHON — OEM defined switch on. 
DIGFFS_USERFFSWITCHOFF— OEM defined switch off. 
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Returns 
SUCCESS Operation was successful. 
DIERR_INVALIDPARAM Invalid parameter encountered. 
DIERR_INPUTLOST Device acquisition is lost. 
DIERR_NOTEXCLUSIVEACQUIRED The device is acquired non-exclusively, or the device is not 
acquired at all. 
DIERR_UNSUPPORTED The device does not support Force Feedback. 


IDirectInputDevice2::EnumEffects 


The EnumEffects method enumerates all IDirectInputEffect object types that are supported by the force 
feedback device. The enumerated GUIDs may represent predefined effects as well as OEM specific effects. 
An application can use the dwEffType field of the DIEFFECTINFO structure to obtain general information 
about the effect, such as its type and which envelope and condition parameters are supported by the effect. 


Syntax 


HRESULT IDirectInputDevice2::EnumEffects(LPDIENUMEFFECTSCALLBACK IpCallback, LPVOID 
pvRef, DWORD dwEffType) 

IN OUT LPDIENUMEFFECTSCALLBACK IpCallback 

IN LPVOID  pvRef 

IN DWORD dwEffType 


Parameters 

eee 

lpCallback Points to an application-defined callback function. For more information, see 
the description of the DIEnumEffectsProc callback function below. 

PvRef Specifies a 32-bit application-defined value to be passed to the callback 
function. This value may be any 32-bit value; it is prototyped as an LPVOID 
for convenience. 

DwEffType Effect type filter. If DIEFT_ALL, then all effect types are enumerated. 
Otherwise, it is a DIEFT_* value, indicating the device type that should be 
enumerated. 

Returns 

eee 

SUCCESS Operation was successful and there is more. 

DIERR_INVALIDPARAM Invalid or NULL parameter encountered. 

DiEnumEffectsProc 


The DIEnumEffectsProc callback function is for use by IDirectInputDevice2::EnumEffects. 
DIEnumEffectsProc returns DIENUM_CONTINUE when the enumeration should be continued and 
DIENUM_STOP when it should be stopped. 


BOOL CALLBACK DIEnumEffectsProc(LPDCDIEFFECTINFO pdei, LPVOID pvRef) 


IN LPDCDIEFFECTINFO pdei Points to a DIEFFECTINFO structure that describes the 
enumerated effect. 
IN OUT LPVOID pvRef Specifies the application-defined value given in the 


IDirectInputDevice2::EnumEffects method. 


SWForce SDK Force Feedback Interface Methods 


IDirectInputDevice2::EnumCreatedEffects 


The EnumCreatedEffects method enumerates all IDirectInputEffect objects that are currently created for 
the force feedback device. Effects created via IDirectInputDevice2::CreateEffect are enumerated. 


Note: Results will be unpredictable if you destroy or create an effect while an enumeration is in progress. 
Syntax 


HRESULT IDirectInputDevice2::EnumCreatedEffects(LPDIENUMCREA TEDEFFECTSCALLBACK 
IpCallback, LPVOID pvRef, DWORD dwflags) 
IN OUT LPDIENUMCREATEDEFFECTSCALLBACK IpCallback 


IN LPVOID pvRef. 

IN DWORD dwFlags 

Parameters 

See 

IpCallback Points to an application-defined callback function. For more information, see 
the description of the DIEnumCreatedEffectsProc callback function below. 

PyRef Reference data (context) for the callback. 

DwFlags No flags are currently defined. This parameter must be 0. 

Returns 

SUCCESS Operation was successful and there is more. 

DIERR_INVALIDPARAM Invalid or NULL parameter encountered. 


DiEnumCreatedEffectsProc 


The DIEnumCreatedEffectsProc callback function is for use by 
IDirectInputDevice2::EnumCreatedEffects. DIEnumEffectsProc returns DIENUM_CONTINUE when 
the enumeration should be continued and DIENUM_STOP when it should be stopped. 


BOOL CALLBACK DIEnumCreatedEffectsProc(LPDIRECTINPUTEFFECT Ipeff, LPVOID pvRef) 


IN LPDIRECTINPUTEFFECT Ipeff Points to a DIRECTINPUTEFFECT interface object. 
IN OUT LPVOID pvRef Specifies the application-defined value given in the 
IDirectInputDevice2::EnumCreatedEffects method. 


IDirectInputDevice2::CreateEffect 


The CreateEffect creates and initializes and instance of an effect identified by the effect GUID and returns a 
pointer to the IDirectInputEffect interface for the effect. 


Syntax 


HRESULT IDirectInputDevice2::CreateEffect(REFGUID rguid, LPCDIEFFECT Ipeff, 
LPDIRECTINPUTEFFECT *ppdeff, LPUNKNOWN punkOuter) 

IN REFGUID _ rguid 

IN LPCDIEFFECT __Ipeff 

OUT LPDIRECTINPUTEFFECT ppdeff 

IN LPUNKNOWN punkOuter 
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Parameters 

-_ SS eS 

rguid The GUID is obtained from EnumEffects or a predefined GUID provided by 
the device manufacturer. 

Lpeff Pointer to a DIEFFECT structure. This parameter is optional. If it is NULL, 
then the effect object is created without parameters. The application must then 
call IDirectInputEffect::SetParameters to set the parameters before being 
downloaded. 

Ppdeff Points to a IDirectInputEffect interface pointer. 

PunkOuter Pointer to controlling unknown for OLE aggregation, or 0 if the interface is 
not aggregated. Most callers will pass 0. 

Returns 

_ eS 

SUCCESS Operation was successful. 

S_FALSE The parameters of the effect were successfully updated, but the effect could not 
be downloaded because the associated device is not acquired in exclusive 
mode. S_FALSE is a success code, because the effect was successfully 
created. 

DIERR_DEVICENOTREG The device does not support this effect GUID. 

DIERR_DEVICEFULL The device download RAM is full. 

DIERR_INVALIDPARAM At least one invalid parameter was encountered. 


IDirectInputDevice2::GetEffectInfo 
The GetEffectInfo method obtains information about a particular effect supported by the device. 
Syntax 


HRESULT IDirectInputDevice2::GetEffectInfo(LPDIEFFECTINFO pdei, REFGUID rguid) 
OUT LPDIEFFECTINFO pdei 
IN REFGUID rguid 


Parameters 

TO  eSSSFSSSSSSSSSmsmMshFsFeSsSsese 

pdei Pointer to a DIEFFECTINFO structure. 

rguid The GUID is obtained from EnumEffects or a predefined GUID provided by 
the device manufacturer. Additionally, the GUID may be obtained from 
IDirectInputEffect::GetEffectGuid. 

Returns 

SUCCESS Operation was successful. 

DIERR_DEVICENOTREG The device does not support this effect GUID. 

DIERR_INVALIDPARAM At least one invalid parameter was encountered. 


IDirectInputEffect::GetEffectStatus 
The GetEffectStatus method returns a DWORD status for the existing effect object. 
Syntax 


HRESULT IDirectInputE ffect::GetEffectStatus(LPD WORD pdwF lags) 
OUT DWORD pdwFlags 
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Parameters 
SS a ee a a 
pdwFlags Pointer to a DWORD to receive the status flags for the effect. The flags are 
DIEGES_XXXX values. 
7 DIEGES_PLAYING — Effect is playing. 
| DIEGES_EMULATED — Effect is emulated. 
Returns 
SUCCESS Operation was successful. 
DIERR_NOTINITIALIZED This object has not been initialized. 
DIERR_INVALIDPARAM At least one of the parameters is invalid. 


IDirectInputEffect::GetParameters 
The GetParameters method returns the DIEFFECT data structure for the existing effect object. 
Note: Make sure that the dwSize member is set to the size of the DIEFFECT structure. 
Syntax 


HRESULT IDirectInputE ffect::GetParameters(LPDIEFFECT pEff, DWORD dwFlags) ° 
OUT LPDIEFFECTpEff 
INDWORD  dwFlags 


Parameters 
pEff Pointer to a DIEFFECT data structure to be filled in with the effect object parameters. 
dwF lags A DIEP_ mask indicating which members to retrieve. For example: 
DIEP_DURATION — dwDuration retrieve 
DIEP_SAMPLEPERIOD — dwSamplePeriod retrieve 
DIEP_GAIN — dwGain retrieve 
DIEP_TRIGGERBUTTON — dwTriggerButton retrieve 
DIEP_TRIGGERREPEATINTERVAL — dwTriggerRepeatInterval retrieve 
DIEP_AXES — dwAxes retrieve 
DIEP_DIRECTION — Direction array retrieve 
DIEP_ENVELOPE — Envelope retrieve 
DIEP_TYPESPECIFICPARAMS — Type specific parameters retrieve 
DIEP_ALLPARAMS— Al! parameters retrieve 
Returns 
SUCCESS Operation was successful. 
DIERR_NOTINITIALIZED Parameters were not previously set. 
DIERR_INVALIDPARAM Invalid or NULL parameter encountered. 


IDirectInputEffect::SetParameters 
The SetParameters method sets the DIEFFECT data structure for the existing effect object. 
Syntax 


SSeS 
HRESULT IDirectInputE ffect::SetParameters(LPCDIEFFECT pEff, DWORD dwFlags) 
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IN LPCDIEFFECT pEff 
INDWORD dwFlags 


Parameters 


=-_ TT CC 


pEf Pointer to the DIEFFECT data structure containing the parameters for the effect object. 
The dwSize member must be filled in by the application before calling this function, as 
well as any members specified by corresponding bits in the dwFlags parameter. 

awF lags Flags specifying which portions of the effect information are to be set and how the 
downloading of the parameters should be handled. The value may be zero, one, or more of 
the following constants: 
DIEP_DURATION - The dwDuration member contains data. 
DIEP_SAMPLEPERIOD - The dwSamplePeriod member contains data. 
DIEP_GAIN - The dwGain member contains data. 


DIEP_TRIGGERBUTTON - The dwTriggerButton member contains data or should 
receive data. 

DIEP_TRIGGERREPEATINTERVAL - The dwTriggerRepeatInterval member 
should receive data. 

DIEP_DIRECTION - The cAxes and rglDirection members contain data. The dwF lags 
member specifies (with DIEFF_CARTESIAN or DIEFF_POLAR) the coordinate system 
in which the values should be interpreted. 

DIEP_ENVELOPE - The IpEnvelope member points to a DIENVELOPE structure that 
contains data. 

DIEP_TYPESPECIFICPARAMS - The cbTypeSpecificParams and 
IpTypeSpecificParams members contain data. Note that the buffer pointed to by 
IpTypeSpecificParams must remain valid for the lifetime of the effect (or until the type- 
specific parameter is set to a new value). DirectInput does not make a private copy of the 
buffer. When retrieving the type-specific parameters, DirectInput merely returns the 
pointers as originally passed to IDirectInputEffect::SetParameters (or implicitly via 
IDirectInputDevice2::CreateEffect). 

DIEP_NODOWNLOAD - Suppress the automatic IDirectInputEffect:: Download that is 
normally performed after the parameters are updated. See Remarks 

DIEP_START - The effect should be started (or restarted if it is currently playing) after 
the parameters are updated. By default, the play state of the effect is not altered. 
DIEP_NORESTART - Suppress the stopping and restarting of the effect in order to 
change parameters. See Remarks. 


Returns 


_ rr OO eee 


SUCCESS Operation was successful. 
DI_LEFFECTRESTARTED The effect was stopped, the parameters updated, and the effect 
restarted 


DI_DOWNLOADSKIPPED The parameters of the effect were successfully updated, but the effect 
could not be downloaded because the associated device was not 
acquired in exclusive mode. 


DIERR_NOTINITIALIZED This object has not been initialized. 


DIERR_INCOMPLETEEFFECT The effect could not be downloaded because essential information is 
missing. For example, no axes have been associated with the effect, or 
no type-specific information has been supplied. 


DIERR_INPUTLOST Access to the input device has been lost. It must be reacquired. 


DIERR_INVALIDPARAM An invalid parameter was passed to the returning function, or the 
object was not in a state that permitted the function to be called. 


35 


SWForce SDK Force Feedback Interface Methods 


DIERR_EFFECTPLA YING The parameters were updated in memory but were not downloaded to 
the device because the device does not support updating an effect 
while it is still playing. 


Remarks 

If the device supports dynamic updating of effect parameters, updating the effect parameters takes effect 
immediately upon download. SideWinder supports this mode. The application should set the 
DIEP_NODOWNLOAD flag if automatic downloading is not desired. 


If automatic download has been suppressed, then you can manually download the effect by invoking the 
IDirectInputEffect::Download method. 


If the effect is playing while the parameters are changed, then the new parameters take effect as if they were 
the parameters when the effect started. 


Only one of the DIEP_NODOWNLOAD, DIEP_START, and DIEP_NORESTART flags should be set. If 
more than one is set, DIEP_NODOWNLOAD overrides the other two, and DIEP_START overrides 
DIJEP_NORESTART. 


These three flags control download and playback behavior as follows: If DIEP_NODOWNLOAD is set, the 
effect parameters are updated but not downloaded to the device. 


If the DIEP_START flag is set, the effect parameters are updated and downloaded to the device, and the 
effect is started just as if the IDirectInputEffect::Start method had been called. (Combining the update with 
DIEP_START is slightly faster than calling Start separately, because it requires less information to be 
transmitted to the device.) 


If neither DIEP_NODOWNLOAD nor DIEP_START is set and the effect is not playing, then the 
parameters are updated and downloaded to the device. 


If neither DIEP_NODOWNLOAD nor DIEP_START is set and the effect is playing, then the parameters 
are updated if the device supports on-the-fly updating. Otherwise the behavior depends on the state of the 
DIEP_NORESTART flag. If it is set, the error code DIERR_EFFECTPLAYING is returned. If it is clear, 
the effect is stopped, the parameters are updated, and the effect is restarted. 


IDirectInputEffect::GetEffectGuid 


The GetEffectGuid method returns the GUID for the existing effect. Additional information about the 
effect may be obtained by passing the GUID to IDirectInputDevice2::GetEffectInfo. 


Syntax 

HRESULT IDirectInputEffect::GetEffectGuid(GUID pGuid) 

OUT LPGUIDpGuid 

Parameters 

pGuid Pointer to a GUID structure. 

Returns é 
SUCCESS Operation was successful. 

DIERR_NOTINITIALIZED The object has not yet been initialized. 

DIERR_INVALIDPARAM Invalid or NULL parameter encountered. 


IDirectInputEffect::Download 
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The Download method downloads the effect and parameters for the existing effect object to the device. If 
the effect is already downloaded, the existing effect is modified with the new values from SetParameters. 


Syntax 
HRESULT IDirectInputEffect::Download(void) 


Returns 


eee 


SUCCESS 
S_FALSE 


DIERR_NOTINITIALIZED 
DIERR_DEVICEFULL 
DIERR_INCOMPLETEEFFECT 


DIERR_INPUTLOST 
DIERR_NOTEXCLUSIVEACQUIRED 


DIERR_INVALIDPARAM 
DIERR_EFFECTPLAYING 


IDirectInputEffect:: Unload 


Operation was successful. 

The effect is already downloaded to the device. S FALSE isa 
success code. 

The object has not yet been initialized. 

Download RAM is full. 

The effect could not be downloaded because essential 
information is missing. For example, no axes have been 
associated with the effect, or no type-specific information has 
been supplied. 

Acquisition of the input device is lost and must be acquired. 
Device is not exclusively acquired, or device is not acquired. 
The operation cannot be performed unless the device is 
acquired in DISCL_EXCLUSIVE mode. 

At least one of the parameters is invalid. 

The parameters were updated in memory but were not 


downloaded to the device because the device does not support 
updating an effect while it is still playing. 


The Unload method stops the effect if it is playing, and removes the effect from the device. 


Syntax 
HRESULT IDirectInputEffect::Unload(void) 


Returns 


oO ----- SSS 


SUCCESS 
S_FALSE 


DIERR_NOTINITIALIZED 
DIERR_INPUTLOST 
DIERR_NOTEXCLUSIVEACQUIRED 


DIERR_INVALIDPARAM 


Operation was successful. 


The effect is already downloaded to the device. S FALSE is a 
success code. 


The object has not yet been initialized. 
Acquisition of the input device is lost and must be acquired. 


Device is not exclusively acquired, or device is not acquired. 
The operation cannot be performed unless the device is 
acquired in DISCL_EXCLUSIVE mode. 


At least one of the parameters is invalid. 
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IDirectInputEffect::Escape 


The The Escape method sends hardware-specific commands to the device driver. 
Syntax 


HRESULT IDirectInputEffect::Escape(LPDIEFFESCAPE pEsc) 
IN LPDIEFFESCAPE pEsc 


Parameters 

pEsc Pointer to a DIEFFESCAPE data structure. 

Returns 

SUCCESS Operation was successful. 

DIERR_NOTINITIALIZED The IDirectInputEffect object has not yet been initialized. 


IDirectInputEffect::Start 


The Start method starts playback of the downloaded effect. A currently playing effect is restarted. The 
device must be previously acquired. 


Syntax 


HRESULT IDirectInputEffect::Start(DWORD dwlterations, DWORD dwFlags) 
IN DWORD  dwiterations 
INDWORD  dwFlags 


Parameters 
eee 
awlterations The number of iterations to repeat the effect playback. Envelopes may or 

may not be preserved for each iteration. The Start options for dwlterations 

are: 

Iteration count -- a positive number. 

Note: SWForce only supports an iteration count of 1. 

INFINITE -- play the effect until stopped. The envelope is preserved. (To 

play the effect without restarting the envelope for each iteration, change the 

effect object’s dwDuration member to INFINITE.) 

adwFlags Flags describing how to play back the effect. It can be zero or any of the 

DIES _ flags. 

DIES_SOLO - effect is played back as the only effect. 
DIES_NODOWNLOAD - Effect is not automatically downloaded to the 
device. 

Returns 

SUCCESS Operation was successful. 

DIERR_NOTINITIALIZED The [DirectInputEffect object has not been initialized or no effect 
parameters have been set. 

DIERR_INCOMPLETEEFFECT The effect could not be downloaded because essential information is 
missing. For example, no axes have been associated with the effect, or 
no type-specific information has been supplied. 

DIERR_UNSUPPORTED The function called is not supported at this time. 

DIERR_INVALIDPARAM Invalid or NULL parameter encountered. 
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IDirectInputEffect::Stop 
The Stop method stops the playing of the effect. 
Syntax 
HRESULT IDirectInputEffect::Stop(void) 


Returns 
SUCCESS Operation was successful. 
DIERR_NOTINITIALIZED The IDirectInputEffect object has not been initialized or no effect parameters 


have been set. 


IVFX::CreateEffectFromFile 


The CreateEffectFromFile method creates an array of effects from an FRC file. 
Syntax 


HRESULT IVFX::CreateEffectFromFile(LPDIRECTINPUTDEVICE2 pDIDevice, 
LPDIRECTINPUTEFFECT* ppDIEffect, LPD WORD pdwEffectCount, const TCHAR* pszFileName, | 
LPVOID pUDBuffer, LPDWORD pdwUDBufferSize, DWORD dwInFlags, LPDWORD pdwOutFlags) 

IN LPDIRECTINPUTDEVICE2 pDIDevice, 

IN OUT LPDIRECTINPUTEFFECT* ppDIEffect, 

IN OUT LPDWORD _ pdwEffectCount, 

IN const TCHAR* pszFileName, 

INLPVOID pUDBuffer, 

IN OUT LPDWORD pdwUDBufferSize, 

INDWORD_  dwinFlags, 

IN OUT LPDWORD _ pdwOutFlags 


Parameters 
pDIDevice Pointer to the DIRECTINPUTDEVICE2 interface. 
ppDIEffect Array of pointers to the DIRECTINPUTEFFECT effect interface. This array 


will receive pointers to the created effects if VFXCE_CREATE_SINGLE or 
VFXCE_CREATE_MULTIPLE is set in dwInFlags. 


pdwEffectCount If VFXCE_CALC_EFFECT_COUNT is set in dwinFlags, this is a pointer 
to a DWORD that receives the number of effects in the file. 
If VFXCE_CREATE_MULTIPLE is set, this is a ptr to a DWORD which 
indicates how many entries there are in the ppDIEffect array. 

pszFileName Pointer to the FRC file that contains the effects data. 

pUDBuffer If the FRC file contains custom forces, a pointer to a buffer from which to get 
custom forces. This parameter can be NULL, in which case the function 
returns an error if an attempt is made to create a custom force effect. 


pawUDBufferSize If VFXCE_CALC_BUFFER_SIZE is set in dwinF) lags, this is a pointer to a 
DWORD which gets the required size of pUDBuffer in bytes. If 
VFXCE_CREATE_SINGLE or VFXCE_CREATE_MULTIPLE is set, 
this is a pointer to a DWORD which contains the size of pUDBuffer in bytes. 


dwinFlags VFXCE_CREATE_SINGLE - Creates a single effect and returns an error if 
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the file contains more than one effect. 
VFXCE_CREATE_MULTIPLE -— Creates multiple effects and places it in 
the ppDIEffect array. 
VFXCE_CALC_BUFFER_SIZE — Calculates the size of the buffer, in 
bytes. The calling function must allocate to hold the custom force samples 
(which are not cached by DirectInput). 
VFXCE_CALC_EFFECT_COUNT - if creating multiple effects, 
calculates the number of entries required in the ppD/Effect array. 
pdwOutFlags Pointer to a DWORD that will receive zero if this is an atomic effect, 
VFXCE_CONCATENATE if the file contains a concatenated effect, and 
VFXCE_SUPERIMPOSE if the file contains a superimpose effect. 


Returns 
SUCCESS Operation was successful. 
SFERR_INVALID_PARAM There is not enough space in ppD/Effect or pdwUDBufferSize 


IVFX::CreateEffectFromBuffer 


The CreateEffectFromBuffer method creates an array of effects from buffer that contains an FRC file. 


Syntax | 


HRESULT IVFX::CreateEffectFromBuffer(LPDIRECTINPUTDEVICE2 pDIDevice, 
LPDIRECTINPUTEFFECT* ppDIEffect, LPD WORD pdwEffectCount, const TCHAR* pszFileName, I 
LPVOID pUDBuffer, LPD WORD pdwUDBufferSize, DWORD dwInFlags, LPDWORD pdwOutFlags) 

IN LPDIRECTINPUTDEVICE2 pDIDevice, 

IN OUT LPDIRECTINPUTEFFECT* ppDIEffect, 

IN OUT LPDWORD  pdwEffectCount, 

IN OUT VOID _ pBuffer, 

INDWORD dwByteCount, 

IN LPVOID pUDBuffer, 

IN OUT LPDWORD pdwUDBufferSize, I 

INDWORD  dwinFlags, 

IN OUT LPDWORD  pdwOutFlags 


Parameters 
pDIDevice Pointer to the DIRECTINPUTDEVICE2 interface. i 
ppDIEffect Array of pointers to the DIRECTINPUTEFFECT effect interface. This array 


will receive pointers to the created effects if WFXCE_CREATE_SINGLE or 
VFXCE_CREATE_MULTIPLE is set in dwinFlags. 


pdawEffectCount If VFXCE_CALC_EFFECT_COUNT is set in dw/nFlags, this is a pointer 
to a DWORD that receives the number of effects in the file. 


If VFXCE_CREATE_MULTIPLE is set, this is a ptr to a DWORD which 
indicates how many entries there are in the ppDJEffect array. 


pBuffer Pointer to the buffer that contains the .FRC file. 
dwByteCount The size of the buffer in bytes. 
pUDBuffer If the FRC file contains custom forces, a pointer to a buffer from which to get 


custom forces. This parameter can be NULL, in which case the function 
returns an error if an attempt is made to create a custom force effect. 
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pdadwUDBufferSize 


dwinF lags 


pawOutFlags 


Returns 


If VFXCE_CALC_BUFFER_SIZE is set in dwInFlags, this is a pointer to a 
DWORD which gets the required size of pUDBuffer in bytes. If 
VFXCE_CREATE_SINGLE or VFXCE_CREATE_MULTIPLE is set in 
dwInF lags, this is a pointer to a DWORD which contains the size of 
pUDBuffer in bytes. 

VFXCE_CREATE_SINGLE - Creates a single effect and returns an error if 
the file contains more than one effect. 

VFXCE_CREATE_MULTIPLE - Creates multiple effects and places it in 
the ppDiEffect array. 

VFXCE_CALC_BUFFER_SIZE — Calculates the size of the buffer, in 
bytes. The calling function must allocate to hold the custom force samples 
(which are not cached by DirectInput). 

VFXCE_CALC_EFFECT_COUNT - If creating multiple effects, 
calculates the number of entries required in the ppD/Effect array. 


Pointer to a DWORD that will receive zero if this is an atomic effect, 
VFXCE_CONCATENATE if the file contains a concatenated effect, and 
VFXCE_SUPERIMPOSE if the file contains a superimpose effect. 


_ > OO rere eee 


SUCCESS 


SFERR_INVALID_PARAM 


Operation was successful. 
There is not enough space in ppDIEffect or pdwUDBufferSize. 
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SWFORCE LIBRARY FUNCTIONS 


SWForce Library Functions 


This chapter provides information on the SWForce library functions. Each function is C-callable and the 
source code is contained in the file SWFF_LIB.cpp. The function prototypes are defined in the sw_force.h 
header file. 


These SWFF_ functions encapsulate the methods of the IDirectInputDevice2 and IDirectInputEffect 
interfaces in ways that greatly simplify force feedback programming in for application. 


SWFF_OpenDefaultFF Joystick 


The SWFF_OpenDefaultFF Joystick function opens the default force feedback joystick in the system and 
retums an IDirectInputDevice2 interface pointer. This function is called by executable applications and does 
not work with DLLs. 


Syntax 


eee 
HRESULT SWFF_OpenDefaultFF Joystick(HWND,LPDIRECTINPUT*, LPDIRECTINPUTDEVICE2*); 

IN HWND hWnd 

OUT LPDIRECTINPUT* ppDI 

OUT LPDIRECTINPUTDEVICE2* ppDIDevice2 


Parameters 
eee 
hWnd Caller’s window handle. 

ppDI Pointer to a DIRECTINPUT device object. 

ppDIDevice2 Pointer to a DIRECTINPUTDEVICE2 interface pointer. 

Returns 


——$— eee 
SUCCESS Device is opened. 


Error code See Appendix A. 


SWFF_OpenDefault¥F FJoystickEx 


The SWFF_OpenDefaultFF Joystick function opens the default force feedback joystick in the system and 
returns an [DirectInputDevice2 interface pointer. This function works with DLLs. 


Syntax 


HRESULT SWFF_OpenDefaultFFJoystickEx(HWND, HINSTANCE, LPDIRECTINPUT*, 
LPDIRECTINPUTDEVICE2*, DWORD); 

IN HWND hWnd 

IN HINSTANCE hinstance 

OUT LPDIRECTINPUT* ppDI 

OUT LPDIRECTINPUTDEVICE2* ppDIDevice2 

IN DWORD dwFlags 
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Parameters 
hWnd Caller’s window handle. | 
hiInstance Instance handle for the DLL. 
ppDI Pointer to a DIRECTINPUT device object. 
ppDIDevice2 Pointer to a DIRECTINPUTDEVICE2 interface pointer. 
adwF lags Cooperative level; for example, DISCL_EXCLUSIVE | 
DISCL_FOREGROUND. 
Returns | 
SUCCESS Device is opened. 
Error code See Appendix A. | 


SWFF_ PutRawForce 


The SWFF_PutRawForce function sends a force vector (magnitude,direction) to the currently acquired 
force feedback device. This requires that the GUID_RawForce effect object be created using the 
SWFF_CreateRawForceEffect library function. 


Syntax 


HRESULT SWFF_PutRawForce(LPDIRECTINPUTEFFECT, LONG, DWORD) 
IN LPDIRECTINPUTEFFECT pDIEffect 


IN LONG IMagnitude 

IN DWORD dwDirection 

Parameters 

pDiEffect Pointer to IDIRECTINPUTEFFECT object. 

lMagnitude Vector force magnitude - in -10000 to +10000 force value. 
dwDirection Vector force direction - in 0 to 35999 degrees. 

Returns 

SUCCESS Force vector is sent to device 

Error code See Appendix A. 


SWFF_PutRawAxisForce 


The SWFF_PutRawAxisForce function sends a force vector (magnitude) to the currently acquired force 
feedback device. This requires that the GUID_RawForce effect object be created using the 
SWFF_CreateRawAxisForceEffect library function. 


Syntax 


HRESULT SWFF_PutRawAxisForce(LPDIRECTINPUTEFFECT, LONG) 
IN LPDIRECTINPUTEFFECT pDIEffect 
IN LONG IMagnitude 


Parameters | 
pDIEffect Pointer to IDIRECTINPUTEFFECT object. 
[Magnitude Vector force magnitude - in -10000 to +10000 force value. 


“| 
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Returns 
SUCCESS Force vector is sent to device 
Error code See Appendix A. 


SWFF _DestroyEffect 


The SWFF_DestroyEffect function invokes an object release, which in turn causes the effect to be 
“destroyed” from the device. 


Syntax 


HRESULT SWFF_DestroyEffect(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFF ECT) 
IN LPDIRECTINPUTDEVICE2 pDIDevice 
IN LPDIRECTINPUTEFFECT pDIEffect 


Parameters 

pDIDevice Pointer to a DIRECTINPUTDEVICE2 object. 

pbDiEffect Pointer to IDIRECTINPUTEFFECT object. Passing a value of NULL, will 
cause ALL effects to be destroyed. 

Returns 

SUCCESS Force effect is released and destroyed from the device. 

Error code See Appendix A. 


SWFF_CreateRawForceEffect 
The SWFF_CreateRawForceEffect function creates a GUID_RawForce effect. 


Syntax 


HRESULT SWFF_CreateRawForceEffect(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFFECT, 
LONG, DWORD ) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN LPDIRECTINPUTEFFECT pDlEffect 

IN LONG [Magnitude 

IN DWORD dwDirection 


Parameters 

pDIDevice Pointer to a DIRECTINPUTDEVICE2 object. 

pDiEffect Pointer to IDIRECTINPUTEFFECT object. 

[Magnitude Vector force magnitude - in -10000 to +10000 force value. 
dwDirection Vector force direction - in 0 to 35999 degrees. 

Returns 

SUCCESS Effect is created. 


Error code See Appendix A. 
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SWFF_CreateRawAxisForceEffect 


The SWFF_CreateRawAxisForceEffect function creates a GUID_RawForce effect that is applies to a | 
single axis. 


Syntax | 
HRESULT SWFF_CreateRawAxisForceEffect(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFFECT, 
LONG, DWORD ) 
IN LPDIRECTINPUTDEVICE2 pDIDevice 
IN LPDIRECTINPUTEFFECT* ppDIEffect 


IN LONG IMagnitude 

IN DWORD dwAxis | 
Parameters 

pDIDevice Pointer to a DIRECTINPUTDEVICE2 object. 

pDiEffect Pointer to IDIRECTINPUTEFFECT object. | 
(Magnitude Vector force magnitude - in -10000 to +10000 force value. 

awAxis Vector force direction: Y_AXIS or X_AXIS. 

Returns 

SUCCESS Effect is created. 

Error code See Appendix A. 


SWFF_CreateROMEffect 


SWFF_CreateROMEffect function creates a built-in ROM effect. 


Syntax 


HRESULT SWFF_CreateROMEffect(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFFECT, 
REFGUID, DWORD, DWORD, DWORD, LONG) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN LPDIRECTINPUTEFFECT pDIEffect 


IN REFGUID refGUID 

IN DWORD dwDuration 

IN DWORD dwDirection 

IN LONG 1Button 

Parameters 

pDIDevice Pointer to a DIRECTINPUTDEVICE2 object. 

pDIEffect Pointer to IDIRECTINPUTEFFECT object. 

refGUID GUID for the effect type. E.g. GUID_Chainsaw. 

dwDuration Duration to play the effect. Normally set to: 
DEFAULT_ROM_EFFECT_DURATION. 

dwDirection Direction angle in degrees. 

[Button Button playback index. 

Returns 


en eee 
SUCCESS Effect is created. 
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Error code 


See Appendix A. 


SWFF_CreatePeriodicEffect 
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The SWFF_CreatePeriodicEffect function creates a DIPERIODIC type effect. 


Syntax 


HRESULT SWFF_CreatePeriodicEffect(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFF ECT, 
DWORD, DWORD, DWORD, DWORD, DWORD, LONG, DWORD, DWORD, DWORD, DWORD, 


LONG) 


IN LPDIRECTINPUTDEVICE2 pDIDevice 
IN LPDIRECTINPUTEFFECT pDIEffect 


IN DWORD dwType 

IN DWORD dwDuration 
IN DWORD dwPeriod 

IN DWORD dwDirection 
IN DWORD dwMagnitude 
IN LONG 1Offset 

IN DWORD dwAttackTime 
IN DWORD dwAttackLevel 
IN DWORD dwFadeTime 
IN DWORD dwFadeLevel 
IN LONG |Button 


Parameters 


pDIDevice 
pDiEffect 
adwType 


dwDuration 
awPeriod 
dwDirection 
dwMagnitude 
lOffset 
awAttackTime 
awAttackLevel 
dwFadeTime 
dwFadeLevel 
/Button 
Returns 


SUCCESS 
Error code 


Pointer to a DIRECTINPUTDEVICE2 object. 
Pointer to IDIRECTINPUTEFFECT object. 
Periodic effect type, for example; 


SINE, COSINE, SQUARE_HIGH, SQUARE_LOW, TRIANGLE_UP, 
TRIANGLE_DOWN, SAWTOOTH_UP, SAWTOOTH DOWN. 


Duration in microseconds. 


Period in microseconds. 


Direction angle in degrees. 

Magnitude in 0 to 10000. 

Envelope offset in —10000 to 10000. 
Envelope attack time in microseconds. 


Envelope attack level. 


Envelope fade time in microseconds. 


Envelope fade level. 


Button playback 


Effect is created. 
See Appendix A. 


index. 
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SWFF_CreateSpringEffect 
The SWFF_CreateSpringEffect function creates a DICONDITION type spring effect. 


Syntax 


HRESULT SWFF_CreateSpringEffect(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFFECT, DWORD 
LONG, LONG, LONG, LONG, LONG) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN LPDIRECTINPUTEFFECT pDIEffect 

IN DWORD dwDuration 

IN LONG IKx 

IN LONG 1!Centerx 

IN LONG IKy 

IN LONG ICentery 

IN LONG [Button 


> 


Parameters 

pD!IDevice Pointer to a DIRECTINPUTDEVICE2 object. 
pDIlEffect Pointer to IDIRECTINPUTEFFECT object. 
dwDuration Duration in microseconds. 

IKx K constant for X-Axis: -10000 to 10000. 
lCenterx Axis center for X-Axis: -10000 to 10000. 
IKy K constant for Y-Axis: -10000 to 10000. 
ICentery Axis center for Y-Axis: -10000 to 10000. 
[Button Button playback index. 

Returns 

SUCCESS Effect is created. 

Error code See Appendix A. 


Note: If zero is passed for an X or Y coefficient constant, then a 1D condition effect is created. If zero is 
passed for both axes, then a 2D condition effect will be created. 


SWFF_CreateDamperEffect 
The SWFF_CreateDamperEffect function creates a DICONDITION type damper effect. 


Syntax 


HRESULT SWFF_CreateDamperEffect(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFFECT, 
DWORD, LONG, LONG, LONG, LONG, LONG) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN LPDIRECTINPUTEFFECT pDIEffect 

IN DWORD dwDuration 

IN LONG IBx 

IN LONG IVOx 

IN LONG IBy 

IN LONG IVOY 

IN LONG [Button 


48 


SWForce Library Functions 
—_—_——_— OSES PD rary Functions — 


Parameters 
pD!IDevice Pointer to a DIRECTINPUTDEVICE2 object. 
pDIEffect Pointer to IDIRECTINPUTEFFECT object. 
awDuration Duration in microseconds. 

[Bx B constant for X-Axis: -10000 to 10000. 
1VOx Initial Velocity for X-Axis: -10000 to 10000. 
IBy B constant for Y-Axis: -10000 to 10000. 
lVOy Initial Velocity for Y-Axis: -10000 to 10000. 
[Button Button playback index. 

Returns 

SUCCESS Effect is created. 

Error code See Appendix A. 


Note: If zero is passed for an X or Y coefficient constant, then a 1D condition effect is created. If zero is 
passed for both axes, then a 2D condition effect will be created. 


SWFF_CreatelInertiaEffect 


The SWFF_CreatelInertiaEffect function creates a DICONDITION type inertia effect. 


Syntax 


HRESULT SWFF_CreateInertiaEffect(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFF ECT, DWORD, 
LONG, LONG, LONG, LONG, LONG) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN LPDIRECTINPUTEFFECT pDIEffect 


IN DWORD dwDuration 

IN LONG IMx 

IN LONG 1A0x 

IN LONG IMy 

IN LONG IAOY 

IN LONG |Button 

Parameters 

pDIDevice Pointer to a DIRECTINPUTDEVICE2 object 
pbDilEffect Pointer to IDIRECTINPUTEFFECT object. 
awDuration Duration in microseconds 

Mx M constant for X-Axis: -10000 to 10000 

lAOx Initial acceleration for X-Axis: -10000 to 10000 
IMy M constant for Y-Axis: -10000 to 10000 

lA0y Initial acceleration for Y-Axis: -10000 to 10000 
[Button Button playback index. 

Returns 

SUCCESS Effect is created. 

Error code See Appendix A. 
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Note: If zero is passed for an X or Y coefficient constant, then a 1D condition effect is created. If zero is 
passed for both axes, then a 2D condition effect will be created. 


SWFF_CreateFrictionEffect 
The SWFF_CreateFrictionEffect function creates a DICONDITION type friction effect. 


Syntax 


HRESULT SWFF_CreateFrictionEffect(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFFECT, 
DWORD, LONG, LONG, LONG, LONG, LONG) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN LPDIRECTINPUTEFFECT pDIEffect 


IN DWORD dwDuration 

IN LONG IFx 

IN LONG IFy 

IN LONG [Button 

Parameters 

pDIDevice Pointer to a DIRECTINPUTDEVICE2 object. 
pDiEffect Pointer to IDIRECTINPUTEFFECT object. 
dwDuration Duration in microseconds. 

IFx F constant for X-Axis: -10000 to 10000. 
IFy F constant for Y-Axis: -10000 to 10000. 
lButton Button playback index. 

Returns 

SUCCESS Effect is created. 

Error code See Appendix A. 


Note: If zero is passed for an X or Y coefficient constant, then a 1D condition effect is created. If zero is 
passed for both axes, then a 2D condition effect will be created. 


SWFF_CreateConditionEffect 
The SWFF_CreateConditionEffect function creates a DICONDITION type effect. 


Syntax 


HRESULT SWFF_CreateConditionEffect(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFFECT, 
DWORD, DWORD, LONG, LONG, LONG, LONG, LONG) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN LPDIRECTINPUTEFFECT pDIEffect 

IN DWORD dwType 

IN DWORD dwDuration 

IN LONG [xCoefficient 

IN LONG IXOffset 

IN LONG 1lYCoefficient 
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IN LONG 1YOffset 


IN LONG [Button 

Parameters 

pDIDevice Pointer to a DIRECTINPUTDEVICE2 object. 
pDiEffect Pointer to IDIRECTINPUTEFFECT object. 
dwDuration Duration in microseconds. 

lXCoefficient Coefficient constant for X-Axis: -10000 to 10000. 
lXOffset Offset for X-Axis: -10000 to 10000. 
lYCoefficient Coefficient constant for Y-Axis: -10000 to 10000. 
lYOffset Offset center for Y-Axis: -10000 to 10000. 
[Button Button playback index. 


Note: If zero is passed for an X or Y coefficient to SWFF_CreateConditionEffect (or one of its derived 
SW_CreateXXXEffect functions), then a 1D condition effect is created. If zero is passed for both axes, 
then a 2D condition effect will be created. 


Returns 

SS eee 
SUCCESS Effect is created. 

Error code See Appendix A. 


SWFF_CreateRampEffect 
The SWFF_CreateRampEffect function creates a DIRAMPFORCE type effect. 


Syntax 


eee 

HRESULT SWFF_CreateRampEffect(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFFECT, DWORD, 
LONG, LONG, DWORD, DWORD, DWORD, DWORD, LONG) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN LPDIRECTINPUTEFFECT pDIEffect 


IN DWORD dwDirection 

IN LONG [Start 

IN LONG lEnd 

IN DWORD dwAttackTime 

IN DWORD dwAttackLevel 

IN DWORD dwFadeTime 

IN DWORD dwFadeLevel 

IN LONG 1Button 

Parameters 

pDIDevice Pointer to a DIRECTINPUTDEVICE2 object. 

pDlEffect Pointer to IDIRECTINPUTEFFECT object. 
Duration in microseconds. 

awDirection Direction angle in degrees. 

[Start Start level in -10000 to 10000. 

[End End level in —10000 to 10000. 

dwAttackTime Envelope attack time in microseconds. 

dwAttackLevel Envelope attack level. 

adwF adeTime Envelope fade time in microseconds. 
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dwFadeLevel Envelope fade level. 
{Button Button playback index. 
Returns 

SUCCESS Effect is created. 

Error code See Appendix A. 


SWFF_CreateConstantForceEffect 
The SWFF_CreateConstantForceEffect function creates a DICONSTANTFORCE type effect. 


Syntax 


HRESULT SWFF_CreateConstantForceE ffect(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFF ECT, 
DWORD, DWORD, LONG, DWORD, DWORD, DWORD, DWORD, LONG) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN LPDIRECTINPUTEFFECT pDIEffect 

IN DWORD dwDuration 

IN DWORD dwDirection 

IN LONG |Magnitude 


IN DWORD dwAttackTime 

IN DWORD dwAttackLevel 

IN DWORD dwFadeTime 

IN DWORD dwFadeLevel 

IN LONG [Button 

Parameters 

pDIDevice Pointer to a DIRECTINPUTDEVICE2 object. 

pDiEffect Pointer to IDIRECTINPUTEFFECT object. 

adwDuration Duration in microseconds. 

dwDirection Direction angle in degrees. 

iMagnitude Magnitude level in —10000 to 10000. 

awAttackTime Envelope attack time in microseconds. 

awAttackLevel Envelope attack level. 

adwFadeTime Envelope fade time in microseconds. 

dwFadeLevel Envelope fade level. 

[Button Button playback index. 

Returns 

SUCCESS Effect is created. 

Error code See Appendix A. 
SWFF_CreateWallEffect J 


The SWFF_CreateWallEffect function creates a SideWinder GUID_Wall type effect. 


Syntax 


HRESULT SWFF_CreateWallEffect(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFFECT, DWORD, 
LONG, LONG, LONG, LONG, LONG) 
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IN LPDIRECTINPUTDEVICE2 pDiDevice 
IN LPDIRECTINPUTEFFECT pDIEffect 


IN DWORD dwDuration 

IN DWORD dwDirection 

IN DWORD dwDistance 

IN BOOL binner 

IN LONG [WallCoefficient 

IN LONG IButton 

Parameters 

pD!IDevice Pointer to a DIRECTINPUTDEVICE2 object. 
pDiEffect Pointer to IDIRECTINPUTEFFECT object. 
dwDuration Duration in microseconds. 

dwDirection Direction 0, 9000, 18000,27000 degrees. 
awDistance Distance from center 0,0 to wall face. 

bInner TRUE = Inner wall type, FALSE = Outer wall type. 
lWallCoefficient Wall constant (strength). 

[Button Button playback index. 

Returns 

SUCCESS Effect is created. 

Error code See Appendix A. 


SWFF_CreateVFXEffectFromFile 


The SWFF_CreateVFXEffectFromFile function creates a Side Winder GUID_VFXEffect type effect from 
an FRC file. 


Syntax 


eee 

HRESULT SWFF_CreateVFXEffectFromFile(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEF FECT*, 
TCHAR *) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN OUT LPDIRECTINPUTEFFECT* ppDiEffect 

IN TCHAR* pszFileName 


Parameters 
in i ee 
pDIDevice Pointer to a DIRECTINPUTDEVICE2 object. 

ppDIEffect Pointer to an IDIRECTINPUTEFFECT object. 

pszFileName Pointer to a valid FRC file name. 

Returns 
ee 
SUCCESS Effect is created. 

Error code See Appendix A. 


SWFF_CreateVFXEffectFromFileEx 


The SWFF_CreateVFXEffectFromFileEx function creates a Side Winder GUID_VFXEffect type effect, 
allowing the caller to override the default VFX settings from Visual Force F actory. 
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Syntax 


IN TCHAR* pszFileName 
IN DWORD dwDuration 
IN DWORD dwGain 

IN DWORD dwDirection 


Parameters 


pDIDevice 
ppDIEffect 
pszFileName 


dwDuration 


dwGain 


dwDirection 


Returns 


SUCCESS 
Error code 


SWFF_CreateVFXEffectFromBuffer 


The SWFF_CreateVFXEffectFromBuffer function creates a Side Winder GUID_VFXEffect type effect 
from a buffer that contains an FRC file. 


Syntax 


HRESULT SWFF_ CreateVFXEffectFromFileEx(LPDIRECTINPUTDEVICE2, 
LPDIRECTINPUTEFFECT*, TCHAR*, DWORD, DWORD, DWORD) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN LPDIRECTINPUTEFFECT* ppDIEffect 


Pointer to a DIRECTINPUTDEVICE2 object. 
Pointer to IDIRECTINPUTEFFECT object. 
Pointer to a valid FRC file name. 

Duration: INFINITE — play forever. 


Use DEFAULT_VFX_EFFECT_DURATION for duration from the original 
FRC attributes. 


Gain: 1 to 10000 


Use DEFAULT_VFX_EFFECT_GAIN for Gain from the original FRC 
attributes. 


Direction: in degrees 0 to 35999 


Use DEFAULT_VFX_EFFECT_DIRECTION for direction from the original 
FRC attributes. 


Effect is created. 
See Appendix A. 


HRESULT SWFF_CreateVFXEffectFromBuffer(LPDIRECTINPUTDEVICE2, 
LPDIRECTINPUTEFFECT*, LPVOID, DWORD) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN OUT LPDIRECTINPUTEFFECT* ppDIEffect 


IN const LPVOID pBuffer 
IN DWORD dwBufferSize 


Parameters 


—eYme3O3c''—v"_____ eo 


pDIDevice 
ppDlEffect 


pBuffer 
awBufferSize 


Pointer to a DIRECTINPUTDEVICE2 object. 
Pointer to an IDIRECTINPUTEFFECT object. 
Pointer to the buffer that contains the FRC file. 
The size of the buffer in bytes. 
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Returns 
SUCCESS Effect is created. 
Error code See Appendix A. 


SWFF_CreateVFXEffectFromBufferEx 


The SWFF_CreateVFXEffectFromBufferEx function creates a SideWinder GUID_VFXEffect type effect 
from a buffer that contains an FRC file. SWFF_CreateVFXEffectFromBufferEx allows the caller to 
override the default VFX settings from Visual Force Factory. 


Syntax 


HRESULT SWFF_ Create VFXEffectFromBufferEx(LPDIRECTINPUTDEVICE2, 
LPDIRECTINPUTEFFECT*, LPVOID, DWORD, DWORD, DWORD, DWORD) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN OUT LPDIRECTINPUTEFFECT* ppDIEffect 


IN const LPVOID pBuffer 

IN DWORD dwBufferSize 

IN DWORD dwDuration 

IN DWORD dwGain 

IN DWORD dwDirection 

Parameters 

pDIDevice Pointer to a DIRECTINPUTDEVICE2 object. 

ppDiEffect Pointer to IDIRECTINPUTEFFECT object. 

pBuffer Pointer to the buffer that contains the FRC file. 

adwBufferSize The size of the buffer in bytes. 

dwDuration Duration: INFINITE -— play forever. 
Use DEFAULT_VFX_EFFECT_DURATION for duration from the original 
FRC attributes. 

dwGain Gain: 1 to 10000 
Use DEFAULT_VFX_EFFECT_GAIN for Gain from the original FRC 
attributes. 

awDirection Direction: in degrees 0 to 35999 
Use DEFAULT_VFX_EFFECT_DIRECTION for direction from the original 
FRC attributes. 

Returns 

SUCCESS Effect is created. 

Error code See Appendix A. 


SWFF_CreateDIEffectFromFile 


The SWFF_CreateDIEffectFromFile function creates a single effect from an FRC file. Unlike 
SWFF_CreateVFXEffectFromFile(...), this function uses the VFX DLL to provide portability across joystick 
devices. SWFF_CreateDIEffectFromFile does not support FRC files containing a custom force effect. 
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Syntax 


HRESULT SWFF_CreateDlEffectFromFile(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFFECT*, 
TCHAR *) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN OUT LPDIRECTINPUTEFFECT* ppDiEffect 


IN TCHAR *pszFileName | 
Parameters 

pDIDevice Pointer to a DIRECTINPUTDEVICE2 object. 

ppDIEffect Pointer to an IDIRECTINPUTEFFECT object. 

pszFileName Pointer to a valid FRC file name. 

Returns 

SUCCESS Effect is created. 

Error code See Appendix A. ; 


SWFF_CreateDIEffectFromFileEx 


The SWFF_CreateDIEffectFromFileEx function creates an array of effects from an FRC file. Unlike 
SWFF_CreateVFXEffectFromFile(...), this function uses the VFX DLL, allowing portability across force 
feedback devices. If there are multiple effects, the effects in the FRC file are returned as an array. It is up to 
the calling function to handle the effects array. 


Syntax 


HRESULT SWFF_ CreateDIEffectFromFileEx(LPDIRECTINPUTDEVICE2, 
LPDIRECTINPUTEFFECT**, PDWORD, TCHAR*, void**, PDWORD) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN OUT LPDIRECTINPUTEFFECT** pppDIEffect 

IN OUT PDWORD pdwEffectCount 

IN TCHAR* pszFileName 

IN OUT void** ppUDBuffer 

IN OUT PDWORD pdwOutFlags 


Parameters 

pD!IDevice Pointer to a DIRECTINPUTDEVICE2 object. 

pppDIEffect Pointer to an array of of LPDIRECTINPUTEFFECT’s. This array is 
allocated by the function. The caller is responsible for deleting the array 
when finished. 

pdawEffectCount Receives the number of effects in the array. 

pszFileName Pointer to a valid FRC file name. 

ppUDBuffer Receives an array containing a cache of custom force samples. This array is 
allocated by the function. The cache is required because DirectInput does not 
cache the samples. The caller is responsible for deleting the array when 
finished. 

pdwOutFlags Receives 0 if the file contains a single effect. Otherwise it receives 
VFXCE_CONCATENATE or VFXCE_SUPERIMPOSE. 

Returns 

SSeS 

SUCCESS Effect is created. 

Error code See Appendix A. 
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SWFF_CreateDIEffectFromBuffer 


CreateDIEffectFromBufferThe SWFF_CreateDIEffectFromBuffer function creates a single effect from a 
buffer that contains an FRC file. Unlike SWFF_Create VFXEffectFromFile(...), this function uses the VFX 
DLL to provide portability across joystick devices. SWFF_CreateDIEffectFromBuffer does not support 
FRC files containing a custom force effect. 


Syntax 


HRESULT SWFF_CreateDJEffectFromBuffer(LPDIRECTINPUTDEVICE2, LPDIRECTINPUTEFFECT*, 
LPVOID, DWORD) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN OUT LPDIRECTINPUTEFFECT* ppDIEffect 


IN const LPVOID pBuffer 

IN DWORD dwBufferSize 

Parameters 
a ee es 
pDIDevice Pointer to a DIRECTINPUTDEVICE2 object. 
ppDIEffect Pointer to an IDIRECTINPUTEFFECT object. 
pBuffer Pointer to the buffer that contains the FRC file. 
awBufferSize The size of the buffer in bytes. 

Returns 

SUCCESS Effect is created. 

Error code See Appendix A. 


SWFF_CreateDIEffectFromBufferEx 


VFXCE_SUPERIMPOSEThe SWFF_CreateDIEffectFromBufferEx function creates an array of effects 
from a buffer that contains an FRC file. Unlike SWFF_CreateVFXEffectFromFile(...), this function uses the 
VFX DLL, allowing portability across force feedback devices. If there are multiple effects, the effects in the 
FRC file are returned as an array. It is up to the calling function to handle the effects array. 


Syntax 


HRESULT SWFF_ CreateDIEffectFromFileEx(LPDIRECTINPUTDEVICE2, 
LPDIRECTINPUTEFFECT**, PDWORD, TCHAR*, void**, PDWORD) 

IN LPDIRECTINPUTDEVICE2 pDIDevice 

IN OUT LPDIRECTINPUTEFFECT** pppDIEffect 

IN OUT PDWORD pdwEffectCount 

IN TCHAR* pszFileName 

IN OUT void** ppUDBuffer 

IN OUT PDWORD pdwOutFlags 


Parameters 
pDIDevice Pointer to a DIRECTINPUTDEVICE2 object. 
pppDIiEffect Pointer to an array of of LPDIRECTINPUTEFFECT's. This array is 


allocated by the function. The caller is responsible for deleting the array 
when finished. 
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pdwEffectCount Receives the number of effects in the array. 
pszFileName Pointer to a valid FRC file name. 
ppUDBuffer Receives an array containing a cache of custom force samples. This array is 


allocated by the function. The cache is required because DirectInput does not 
cache the samples. The caller is responsible for deleting the array when 


finished. 
pdwOutFlags Receives 0 if the file contains a single effect. Otherwise it receives 
VFXCE_CONCATENATE or VFXCE_SUPERIMPOSE. 
Returns 
SUCCESS Effect is created. 
Error code See Appendix A. 


SWFF _SetGain 
The SWFF_SetGain function sets the dwGain member in the effect object. 
Syntax 


HRESULT SWFF_SetGain(LPDIRECTINPUTEFFECT, DWORD) 
IN LPDIRECTINPUTEFFECT pDlEffect 


IN DWORD dwGain 

Parameters 

pDIEffect Pointer to IDIRECTINPUTEFFECT object. 
dwGain Gain to set. Range 1 to 10000. 

Returns 

SUCCESS Gain is set. 

Error code See Appendix A. 


SWFF_SetDirection 
The SWFF_SetDirection function sets the direction members in the effect object. 
Syntax 


HRESULT SWFF_SetDirection(LPDIRECTINPUTEFFECT, DWORD) 
IN LPDIRECTINPUTEFFECT pDIEffect 


IN DWORD dwDirection 

Parameters ; 
pDiEffect Pointer to IDIRECTINPUTEFFECT object. 

dwDirection Direction to set. Range 0 to 35999. 

Returns 
a ee 
SUCCESS Direction is set. 

Error code See Appendix A. 
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SWFF_SetDuration 


The SWFF_SetDuration function sets the dwDuration member in the effect object. 


Syntax 


HRESULT SWFF_SetDuration(LPDIRECTINPUTEFFECT, DWORD) 
IN LPDIRECTINPUTEFFECT pDIEffect 


IN DWORD dwDuration 

Parameters 
re 
pDiEffect Pointer to IDIRECTINPUTEFFECT object. 

dwDuration Duration to set in microseconds. 

Returns 

SUCCESS Duration is set. 

Error code See Appendix A. 


SWFF_RegisterVFXObject 


The SWFF_RegisterVFXObject function creates the necessary registry entries for the VFX COM object. 


Syntax 

HRESULT SWFF_RegisterVFXObject(LPCTSTR) 

IN LPCTSTR IpszVFXPath 

Parameters 

lpszVF XPath Pointer to the fully-qualified path name of VFX.DLL. 

Returns 
eee 
SUCCESS The object was successfully registered. 

Error code See Appendix A. 
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CHAPTER 5 


SWFORCE SDK FORCE FEEDBACK DATA 
STRUCTURES 


This chapter provides information on the data structures used by the IDirectInputDevice, 
IDirectInputDevice2, and IDirectInputEffect interfaces that are relevant to SideWinder and Force 
Feedback. Refer to your DirectInput documentation for a more detailed and complete description of the data 
structures used by the DirectInput subsystem. This chapter also includes a section that describes predefined 
GUIDs. 


DIENVELOPE 


The DIENVELOPE structure defines the attack, sustain, and decay times used to modify periodic, user- 
defined force, ramp, and ROM-based effects. Additionally, this structure defines the initial and ending 
amplitudes for the time-based envelope. 


typedef struct DIENVELOPE { 
DWORD dwSize; 
DWORD dwAttackLevel; 
DWORD dwAttackTime; 
DWORD dwFadeLevel; 
DWORD dwFadeTime; 
} DIENVELOPE, *LPDIENVELOPE; 
typedef const DIENVELOPE *LPCDIENVELOPE; 


Members 

dwSize Size of this structure in bytes. 

dwAttackLevel Amplitude to start the envelope, relative to baseline offset. Range is 0 to 10000. 

dwAttackTime Time, expressed in microseconds, from the start of the effect until the forces reach the 
sustained amplitude. . 

dwFadeLevel Amplitude to end the envelope, relative to baseline offset. Range is 0 to 10000. 

dwFadeTime Time, expressed in microseconds, that the effect begins to fade to the Fade Level. 
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Initial Attack Amplitude: 


dwAttackLevel 
Decay Amplitude: 
: i F 1 
1Offset L | dwFadeLeve 
ee Zero Force Baseline 


al : ' Level 


N 


mia enimnast enn hie ene seen 


dwAttackTime in us 


dwSustainTime in se eee 


DwFadeTime in us ¢—» 


Total dwDuration in us 


or sereormn mete ee Thanet eens 
n 


Note: The offset member [Offset is taken from the DIPERIODIC structure. 
In the case of a DIRAMPFORCE, this value is derived as (Start + IEnd)/2. 
In the case of DICONSTANTFORCE, lOffset is assumed to be zero. 


Time-based Envelope 


Refer also to Appendix E, SWForce Waveforms, Envelopes, and Offsets for additional information on 
envelopes. 


DIEFFECT 


The DIEFFECT structure describes the type of effect and its general characteristics. Additional information 
regarding the effect is contained in the structure named in the type specific data structure. 


typedef struct { 
DWORD dwSize; 
DWORD dwFlags; 
DWORD dwDuration; 
DWORD dwSamplePeriod; 
DWORD dwGain; 
DWORD dwTriggerButton; 
DWORD dwTriggerRepeatInterval; 
DWORD cAxes; 
LPDWORD rgdwAxes; 
LPDWORD rglDirection; 
LPDIENVELOPE lpEnvelope; 
DWORD cbhTypeSpecificParams; 
LPVOID lpvTypeSpecificParams; 


} DIEFFECT; 

Members 

dwSize Size of this structure in bytes. 

dwFlags Flags associated with Effect: For example, DIEFF_ type 


DIEFF_OBJECTIDS 


DIEFF_OBJECTOFFSETS 
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dwDuration 
dwSamplePeriod 


dwGain 


dwTriggerButton 


dwTriggerRepeatInterval 


cAxis 
rgdwAxes 


rglDirection 


IpEnvelope 
cbTypeSpecificParams 
LpvTypeSpecificParams 
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DIEFF_CARTESIAN 

DIEFF_POLAR 

DIEFF_SPHERICAL 

Duration in microseconds. INFINITE = infinite or forever. 0 = STOP. 


The period at which the device should play back the effect, in microseconds. A 
value of zero indicates that the default playback sample rate should be used. 


The gain to be applied to the effect, in the range 0 to 10000, with the default 
value set to 10000. If attenuation is needed, reduce the dwGain value 
appropriately. (Force strength variation between different devices can be 
compensated for with the dwGain member.) 


The identifier or offset of the button to be used to trigger playback of the effect. 
The flags DIEFF_OBJECTIDS and DIEFF_OBJECTOFFSETS determine the 
semantics of the value. Set this to DEIB_LNOTRIGGER for no trigger playback. 


The delay, in microseconds, before restarting the effect when triggered by a 
button press. 


Number of axes for the Effect. 


Pointer to a DWORD array (of cAxes elements) containing identifiers or offsets 
identifying the axes to which the effect is to be applied. The flags 
DIEFF_OBJECTIDS and DIEFF_OBJECTOFFSETS determines array usage. 


Maximum is 32 axes. This value cannot be changed once an effect is created. 


Pointer to a LONG array (of cAxes elements) containing either Cartesian 
coordinates or polar coordinates. The flags DIEFF_CARTESIAN. 
DIEFF_POLAR, and DIEFF_SPHERICAL determine the semantics of the 
values in the array. 


If Cartesian, then each value in rg/Direction is associated with the corresponding 
axis in rgdwAxes. 


If polar, then the angle is measured in hundredths of degrees from the (0, -1) 
direction, rotated in the direction of (1, 0). This usually means that “north” is 
away from the user, and “east” is to the user’s right. The last element is not used. 


If spherical, then the first angle is measured in hundredths of degrees from the qd, 
0) direction, rotated in the direction of (0, 1). The second angle (if the number of 
axes is three or more) is measured in hundredths of degrees towards (0, 0, 1). The 
third angle (if the number of axes is four or more) is measured in hundredths of 
degrees towards (0, 0, 0, 1), and so on. The last element is not used. 


Note The rg/Direction array must contain cAxes entries, even if polar or 
spherical coordinates are given. The last element in the rg/Direction array is 
reserved for future use and must be zero. 


Pointer to a DIENVELOPE structure. If no envelope is needed, use NULL. 
Number of bytes in the following TypeSpecificParams data structure (array). 


Pointer to type-specific parameters, or NULL if there are no type-specific 
parameters. For the following types, the type specific pointers are: 


DIEFT_CONDITION — DICONDITION 
DIEFT_CUSTOMFORCE — DICUSTOMFORCE 
DIEFT_PERIODIC — DIPERIODIC 

DIEFT_CONSTANTFORCE — DICONSTANTFORCE 
DIEFT_RAMPFORCE — DIRAMPFORCE 

The following types are SideWinder force feedback device specific only: 
BE_WALL_PARAM — GUID_ Wail Effect 

VFX_PARAM — GUID_VFXEffect Effect 
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DIEFFECTINFO 


The DIEFFECTINFO structure is used by the IDirectInputDevice2::EnumEffects and | 
IDirectInputDevice2::GetEffectInfo methods to return information about a particular effect supported by a 
device. 


typedef struct { 
DWORD dwSize; 
GUID guid; 
DWORD dwEffType; 
DWORD dwStaticParams; 
DWORD dwDynamicParams; 
TCHAR tszName [MAX PATH]; 
} DIEFFECTINFO, *LPDIEFFECTINFO; 


Members 
eee 

dwSize Size of this structure in bytes. 

guid The identifier for the effect. i 
dwEffType None, one, or more of the following values: 


DIEFT_ALL - Valid only for IDirectInputDevice2::EnumEffects. Enumerate all 
effects, regardless of type. This flag may not be combined with any other flags. 


DIEFT_CONSTANTFORCE - The effect represents a constant-force effect. When 
creating or modifying a constant-force effect, the lpyTypeSpecificParams member of 
the DIEFFECT structure must point toa DICONSTANTFORCE structure and the 
cbTypeSpecificParams member must be set to sizeof(DICONSTANTFORCE). The flag 
can be passed to IDirectInputDevice2::EnumEffects to restrict the enumeration to 
constant-force effects. 


DIEFT_RAMPFORCE - The effect represents a ramp-force effect. When creating or 
modifying a ramp-force effect, the IpvTypeSpecificParams member of the DIEFFECT 
structure must point to a DIRAMPFORCE structure and the cbTypeSpecificParams 
member must be set to sizeof(DIRAMPFORCE). The flag can be passed to 
IDirectInputDevice2::EnumEffects to restrict the enumeration to ramp-force effects. 


DIEFT_PERIODIC - The effect represents a periodic effect. When creating or 
modifying a periodic effect, the IlpvTypeSpecificParams member of the DIEFFECT 
structure must point to a DIPERIODIC structure and the cbTypeSpecificParams 
member must be set to sizeof(DIPERIODIC). The flag can be passed to 
IDirectinputDevice2::EnumEffects to restrict the enumeration to periodic effects. 


DIEFT_CONDITION - The effect represents a condition. When creating or modifying 
a condition, the IlpvTypeSpecificParams member of the DIEFFECT structure must 
point to an array of DICONDITION structures (one per axis) and the 
cbTypeSpecificParams member must be set to cAxis * sizeof(DICONDITION).Not all 
devices support all the parameters of conditions. Check the effect capability flags to 
determine which capabilities are available.The flag can be passed to 
IDirectInputDevice2::EnumEffects to restrict the enumeration to conditions. 


DIEFT_CUSTOMFORCE - The effect represents a custom-force effect. When creating 
or modifying a custom-force effect, the lpyTypeSpecificParams member of the 
DIEFFECT structure must point to a DICUSTOMFORCE structure and the 
cbTypeSpecificParams member must be set to sizeof(DICUSTOMFORCE). The flag 
can be passed to IDirectInputDevice2::EnumEffects to restrict the enumeration to 
custom-force effects. 


DIEFT_FFATTACK - The effect generator for this effect supports the attack envelope 
parameter. If the effect generator does not support attack then the attack level and attack 
time parameters of the DIENVELOPE structure will be ignored by the effect. If neither 
DIEFT_FFATTACK nor DIEFT_FFFADE is set, then the effect does not support an 
envelope, and any provided envelope will be ignored. 
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DIEFT_FFFADE - The effect generator for this effect supports the fade parameter. If 
the effect generator does not support fade then the fade level and fade time parameters of 
the DIENVELOPE structure will be ignored by the effect. If neither 
DIEFT_FFATTACK nor DIEFT_FFFADE is set, then the effect does not support an 
envelope, and any provided envelope will be ignored. 


DIEFT_HARDWARE - The effect represents a hardware-specific effect. For additional 
information on using a hardware-specific effect, consult the hardware documentation. 
The flag can be passed to the IDirectInputDevice2::EnumEffects method to restrict the 
enumeration to hardware-specific effects. 


DIEFT_SATURATION - The effect generator for this effect supports the saturation of 
condition effects. If the effect generator does not support saturation, then the force 
generated by a condition is limited only by the maximum force that the device can 
generate. 


DIEFT_POSNEGCOEFFICIENTS - The effect generator for this effect supports two 
coefficient values for conditions, one for the positive displacement of the axis and one 
for the negative displacement of the axis. If the device does not support both 
coefficients, then the negative coefficient in the DICONDITION structure will be 
ignored and the positive coefficient will be used in both directions. 


DIEFT_POSNEGSATURATION - The effect generator for this effect supports a 
maximum saturation for both positive and negative force output. If the device does not 
support both saturation values, then the negative saturation in the DICONDITION 
structure will be ignored and the positive saturation will be used in both directions. 


dwStaticParams Zero or more DIEP_* values describing the parameters supported by the effect. For 
example, if DIEP_ENVELOPE is set, then the effect supports an envelope. For a list of 
possible values, see IDirectInputEffect::GetParameters. 


It is not an error for an application to attempt to use effect parameters which are not 
supported by the device. The unsupported parameters are merely ignored. 


This information is provided to allow the application to tailor its use of force feedback to 
the capabilities of the specific device. 


dwDynamicParams Zero or more DIEP_* values describing the parameters of the effect which can be 
modified while the effect is playing. For a list of possible values, see 
IDirectInputEffect::GetParameters. 


If an application attempts to change a parameter while the effect is playing, and the 
driver does not support modifying that effect dynamically, then the status code 
DIERR_EFFECTPLAYING will be returned. 


This information is provided to allow the application to tailor its use of force feedback to 
the capabilities of the specific device. 


tszName Name of the effect; for example, "Sawtooth up” or "Constant force". 


DIDEVCAPS 
The DIDEVCAPS structure describes a force feedback device and its capabilities. 


typedef struct { 
DWORD dwSize; 
DWORD dwFlags; 
DWORD dwDevType; 
DWORD dwAxes; 
DWORD dwButtons; 
DWORD dwPOVs; 
DWORD dwFFSamplePeriod; 
DWORD dwFFMinTimeResolution; 
DWORD dwFirmwareRevision; 
DWORD dwHardwareRevision; 
DWORD dwDriverVersion; 
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} DIDEVCAPS; 


Members 


dwSize 
dwF lags 


dwDevType 


dwAxes 

dwButtons 

dwPOVs 
dwFFSamplePeriod 
dwFFMinTimeResolution 


Size of this structure in bytes. 

Flags associated with the device. The following flags are defined: 
DIDC_ATTACHED.: The device is physically attached. 
DIDC_POLLEDDEVICE: The device is polled rather than interrupt-driven. 
The application must explicitly call GetDeviceState in order to obtain data; 
buffering and event notifications will be ineffective. 

DIDC_EMULATED.: Device functionalty is emulated. 
DIDC_FORCEFEEDBACK: The device supports force feedback. 
DIDC_FFFADE: The force feedback system supports the fade parameter for at 


least one effect. If the device does not support fade then the fade level and fade 
time parameters of the DIENVELOPE structure will be ignored by the device. 
Individual effects will set the DIEFT_FFFADE flag if fade is supported for that 
particular effect. 

DIDC_FFATTACK: The force feedback system supports the attack envelope 
parameter for at least one effect. If the device does not support attack then the 
attack level and attack time parameters of the DIENVELOPE structure will be 
ignored by the device. 

Individual effects will set the DIEFT_FFATTACK flag if attack is supported for 
that particular effect. 

DIDC_SATURATION: The force feedback system supports the saturation of 
condition effects for at least one condition. If the device does not support 
saturation, then the force generated by a condition is limited only by the 
maximum force which the device can generate. 

Individual conditions will set the DIEFT_SATURATION flag if saturation is 
supported for that particular condition. 

DIDC_POSNEGCOEFFICIENTS: The force feedback system supports two 
coefficient values for conditions (one for the positive displacement of the axis 
and one for the negative displacement of the axis) for at least one condition. If 
the device does not support both coefficients, then the negative coefficient in the 
DICONDITION structure will be ignored. 

Individual conditions will set the DIEFT_POSNEGCOEFFICIENTS flag if 
separate positive and negative coefficients are supported for that particular 
condition. 

DIDC_POSNEGSATURATION: The force feedback system supports a 
maximum saturation for both positive and negative force output for at least one 
condition. If the device does not support both saturation values, then the negative 
saturation in the DICONDITION structure will be ignored. 

Individual conditions will set the DIEFT_POSNEGSATURATION flag if 
separate positive and negative saturations are supported for that particular 
condition. 

Device type specifier. This member can contain values identical to those in the 
dwDevType member of the DIDEVICEINSTANCE structure. 

Number of output axes available on the device. 

Number of buttons available on the device. 

Number of point-of-view controllers available on the device. 

The minimum time between playback of consecutive raw force commands. 


The minimum amount of time, in microseconds, that the device can resolve. The 
device rounds any time periods to the nearest supported increment. For example, 
if the value of dwFFMinTimeResolution is 1000, then the device would round 
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times to the nearest millisecond. 

Specifies the firmware revision of the device. 
The hardware revision of the device. 

The version number of the device driver. 


The DIDEVICEINSTANCE structure contains information about an instance of a DirectInput device. This 
structure is used with IDirectInputDevice::GetDevicelnfo. 


typedef struct { 
DWORD dwSize; 
GUID guidInstance; 
GUID guidProduct; 
DWORD dwDevType; 


TCHAR tszInstanceName [MAX PATH]; 
TCHAR tszProductName [MAX PATH]; 


GUID guidFFDriver; 
WORD wUsagePage; 
WORD wUsage; 


} DIDEVICEINSTANCE, *LPDIDEVICEINSTANCE; 


Members 


TT  - ————  —eeeeeeeeeee 


dwSize 
guidInstance 


guidProduct 


dwDevType 


Size of this structure, in bytes. 


Unique identifier for the instance of the device. An application may save the 
instance GUID into a configuration file and use it at a later time. Instance GUIDs 
are specific to a particular computer. An instance GUID obtained from one 
computer is unrelated to instance GUIDs on another. 


Unique identifier for the product. This identifier is established by the 
manufacturer of the device. 


Device type specifier. The least-significant byte of the device type description 
code specifies the device type. The next-significant byte specifies the device 
subtype. This value can be one of the following types combined with their 
respective subtypes and optionally with DIDEVTYPE_HID, which specifies a 
Human Interface Device. 


DIDEVTYPE_MOUSE - A mouse or mouse-like device (such as a trackball). 
This value cannot be used with the DIDEVTYPE_KEYBOARD value. 


DIDEVTYPE_KEYBOARD - A keyboard or keyboard-like device. This value 
cannot be used with the DIDEVTYPE_MOUSE value. 


DIDEVTYPE_JOYSTICK - A joystick or similar device, such as a steering 
wheel 


DIDEVTYPE_DEVICE - A device that does not fall into the above categories 
The following subtypes are defined for mouse-type devices. 
DIDEVTYPEMOUSE_UNKNOWN - The subtype could not be determined. 
DIDEVTYPEMOUSE_TRADITIONAL - The device is a traditional mouse. 
DIDEVTYPEMOUSE_FINGERSTICK - The device is a fingerstick. 
DIDEVTYPEMOUSE_TOUCHPAD - The device is a touchpad. 
DIDEVTYPEMOUSE_TRACKBALL - The device is a trackball. 

The following subtypes are defined for keyboard-type devices. 


DIDEVTYPEKEYBOARD_UNKNOWN - The subtype could not be 
determined 


DIDEVTYPEKEYBOARD PCXT - IBM PC/XT 83-key keyboard. 
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DIDEVTYPEKEYBOARD_OLIVETTI - Olivetti 102-key keyboard. 
DIDEVTYPEKEYBOARD PCAT - IBM PC/AT 84-key keyboard. 


DIDEVTYPEKEYBOARD_PCENH - IBM PC Enhanced 101/102-key or 
Microsoft Natural keyboard. 


DIDEVTYPEKEYBOARD_NOKIA1050 - Nokia 1050 keyboard. 
DIDEVTYPEKEYBOARD_NOKIA9140 - Nokia 9140 keyboard. 
DIDEVTYPEKEYBOARD_NEC98 - Japanese NEC PC98 keyboard. 


DIDEVTYPEKEYBOARD_NEC98LAPTOP - Japanese NEC PC98 laptop 
keyboard. 


DIDEVTYPEKEYBOARD_NEC98106 - Japanese NEC PC98 106-key 
keyboard. 


DIDEVTYPEKEYBOARD_JAPAN106 - Japanese 106-key keyboard. 
DIDEVTYPEKEYBOARD_JAPANAxX - Japanese AX keyboard. 
DIDEVTYPEKEYBOARD_J3100 - Japanese J3100 keyboard. 


The following subtypes are defined for joystick-type devices. 
DIDEVTYPEJOYSTICK_UNKNOWN - The subtype could not be 
determined. 

DIDEVTYPEJOYSTICK_TRADITIONAL - A traditional joystick. 
DIDEVTYPEJOYSTICK_FLIGHTSTICK - A joystick optimized for flight 
simulation. 

DIDEVTYPEJOYSTICK_GAMEPAD - A joystick whose primary purpose is 
to provide button input. 

DIDEVTYPEJOYSTICK_RUDDER - A joystick optimized for yaw control. 
DIDEVTYPEJOYSTICK_WHEEL - A joystick optimized for use as a steering 
wheel. 

The high-order word of the device type description code contains flags that 
further identify the device. 

DIDEVTYPE_HID - The device uses the Human Input Device (HID) protocol. 


tszInstanceName Friendly name for the instance. For example, "Joystick 1." 

tszProductName Friendly name for the product. 

guidFF Driver Unique identifier for the driver being used for force feedback. This identifier is 
established by the manufacturer of the driver. 

wUsagePage If the device is a HID device, then this member contains the HID usage page 
code. 

wUsage If the device is a HID device, then this member contains the HID usage code 


For compatibility with previous versions of DirectX, a DIDEVICEINSTANCE_DX3 structure is also 
defined, containing only the first six members of the DIDEVICEINSTANCE structure. 


DICONDITION 


This section describes the structure for behavioral effects. 


typedef struct DICONDITION { 
LONG l10ffset; 
LONG l1PositiveCoefficient; 
LONG l1NegativeCoefficient; 
DWORD dwPositiveSaturation; 
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DWORD dwNegativeSaturation; 
LONG l1DeadBand; 
} DICONDITION, *LPDICONDITION; 


Members 

lOffset The offset for the condition. Range is -10000 to +10000. 

[PositiveCoefficient The coefficient constant (Spring, Damper, Inertia, Friction) for the positive 
side of the offset. Range is -10000 to +10000. 

INegativeCoefficient The coefficient constant (Spring, Damper, Inertia, Friction) for the negative 
side of the offset. Range is -10000 to +10000. 

[PositiveSaturation The maximum positive force. 

INegativeSaturation The maximum negative force. 

IDeadband The region around the offset where the condition is not active. 


The following table lists the Side Winder specific behavioral effects members to be stored in the DICONDITION data 
structure when creating a DICONDITION effect. Note that this is a 1D effect. Fora 2D effect, the TypeSpecificParam 
array will contain two of the DICONDITION structures. The table illustrates the X-Axis condition. SideWinder does 
not support separate !PositiveCoefficient and INegativeCoefficient, or PositiveSaturation and INegativeSaturation. 


DICONDITION Member Spring Damper Inertia Friction 
eee 
lOffset +/- CenterX +/- VelocityX +/- AccelerationX 0 
IPositiveCoefficient +/- KX +/- BX +/- MX +/- FX 
INegativeCoefficient 0 0 0 0 
IPositiveSaturation 0 0 0 0 
INegativeSaturation 0 0 0 0 
IDeadband 0 0 0 0 
DIPERIODIC 


The DIPERIODIC structure is typically used to describe synthesized effects that are periodic, such as 
earthquake movement, pulses, and hits. 


typedef struct { 
DWORD dwMagnitude; 
LONG 10ffset; 
DWORD dwPhase; 
DWORD dwPeriod; 

} DIPERIODIC; 


Members 

dwMagnitude Magnitude of Forces. Range is 0 to 10,000. If an envelope is applied, this value 
represents the Sustain amplitude. If no envelope is applied, then the value represents 
the Effects magnitude. 

lOffset The range of forces generated by the effect will be lOffset-dwMagnitude to 
lOffset+dwMagnitude. ; 

dwPhase The position in the periodic effect at which playback begins, in the range 0 to 35999. 

dwPeriod Effect period in microseconds. 


The valid Side Winder periodic effects are: 
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Periodic Effect GUID 
Sine waveform GUID_Sine 
Cosine waveform GUID_Cosine (to be implemented after 1.1) i 
Square waveform GUID_Square 
GUID_SquareLow (to be implemented after 1.1) 
Triangle waveform GUID_TriangleUp 
GUID_TriangleDown 
Sawtooth positive waveform GUID_SawtoothUp 
Sawtooth negative waveform GUID_SawtoothDown 
DIEFFESCAPE 


The DIEFFESCAPE is used by the IDirectInputEffect::Escape method to pass hardware-specific data 
directly to the device driver. 


typedef struct { 
DWORD dwSize; 
DWORD dwCommand; 
LPVOID lpviInBuffer; 
DWORD cbInBuffer; 
LPVOID lpvOutBuffer; 
DWORD cbOutBuffer; 
} DIEFFESCAPE, *LPDIEFFESCAPE; 


Members 

dwSize Size of this structure in bytes. 

dwCommand Driver-specific command number. Consult the driver documentation for a list of valid 
commands. 

IpvInBuffer Buffer containing the data required to perform the operation. 

cbInBuffer The size, in bytes, of the IpvInBuffer buffer. 

IpvOutBuffer Buffer in which the operation's output data is returned. 

cbOutBuffer On entry, the size in bytes of the IpvOutBuffer buffer. On exit, the number of bytes actually 
produced by the command. 

Remarks 


Since each driver implements different escape sequences, it is the responsibility of the application to ensure 
that it is communicating with the correct driver. The application can check this by comparing the 
guidFFDriver member in the DIDEVICEINSTANCE structure against the value expected by the 
application. 


DICONSTANTFORCE 


The DICONSTANTFORCE structure is used to describe a constant force effect. The effect GUID is 
GUID_ConstantForce. 


typedef struct { 
LONG 1Magnitude; 
} DICONSTANTFORCE; 
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Members 


eee 


[Magnitude Magnitude of Force to output. Valid range is —10000 to +10000 


DIRAMPFORCE 
The DIRAMPFORCE structure is used to describe a Ramp force effect. The effect GUID is GUID_Ramp. 


typedef struct { 
LONG lStart; 
LONG 1End; 

} DIRAMPFORCE; 


Members 

oo SeSeSeSeSSSSSSSSSSSSSSSSSSSSSSSSSSssFseseseSS 
IStart Magnitude at the start of the effect. Valid range is —10000 to +10000 

IEnd Magnitude at the end of the effect. Valid range is —10000 to +10000 


BE_WALL_PARAM 


The BE_WALL_PARAM structure is used to describe wall effects. The effect GUID is GUID_Wall. 


typedef struct BE WALL PARAM { 
ULONG m_Bytes; 
ULONG m_WallType; 
LONG m_WailConstant; 
ULONG m _WallAngle; 
ULONG m_WallDistance; 
} BE_WALL_PARAM, *PBE_WALL PARAM; 


Members 


eo ,?) ee SSSFSFSSSeSeSSSSeSSSFSSSSSSSSSSSSSSSSSSSSeeSSee 
m_Bytes Size of this structure in bytes. 
m_WallType Type of wall: 
WALL_INNER — one that exhibits resistance to movement as some point toward the 
center position (which is ‘inside’ the wall) of the force feedback device. 
WALL_OUTER — one that exhibits resistance to movement as some point away from the 
center position (which is ‘outside’ the wall) of the force feedback device. 
m_WallConstant The wall coefficient, the amount of resistance offered by the wail. Valid values are in the 
range of +/-10000. 
m_WallAngle The angle of the wall relative to the center position of the force feedback device. An angle 


of 0 means that the wall is directly in front of the device, while an angle of 27000 places the 
wall in a ‘west’ position from the center of the device. The only valid angles are 0, 9000, 
18000, and 27000. 


m_WallDistance The distance from the wall face to joystick center position. Distance is expressed as a 
percentage of maximum device movement; valid values are 0-10000. 


Complex Effect Structures 


User defined effect VFXEffect structures define more complex effects not easily represented by synthesizing 
or other algorithms. These structures are generated by the Visual Force Factory tool. 


Effect SubType 


User-defined waveform GUID_CustomForce 
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VFX/FRC effect GUID_VFXEffect 


DICUSTOMFORCE 


The DICUSTOMFORCE structure is used to describe user-defined waveform effects. These effects are 
waveform sampled data. 


typedef struct { 
DWORD cChannels; 
DWORD dwSamplePeriod; 
DWORD cSample; 
LPLONG rglForceData; 


} DICUSTOMFORCE; 

Members 

cChannels Number of channels in the sample data array. 

dwSamplePeriod Sample period that the data was sampled at, in microseconds. 

cSample Number of samples in rgiForceData. 

rglForceData Pointer to an array of force values representing the custom force. 
If multiple axes are affected by the force, then the values are interleaved. For example, 
if cChannels is 3, then the first element of the array is applied to the first axis, the 
second to the second, and the third to the third. After dwSamplePeriod microseconds, 
the fourth element of the array is applied to the first axis, the fifth to the second, and the 
sixth to the third, and so on. 
SideWinder only supports a single array sent to both X- and Y-axis. 

VFX_PARAM 


The VFX_PARAM structure describes SideWinder VFX/FRC effects. The effect GUID is 
GUID_VFXEffect. 


typedef struct _VFX_PARAM 
{ 

ULONG m_Bytes; 

ULONG m_PointerType; 

ULONG m_BufferSize; 

PVOID m_pFileNameOrBuffer; 
} VEFX_PARAM, *PVFX_PARAM; 


Members 
m_Bytes Size of this structure in bytes. 
m_PointerType VFX_FILENAME: Pointer is to a file name. 
VFX_BUFFER: Pointer is to a VFX buffer. 
m_BufferSize Number of bytes in the buffer if VFX_BUFFER. 
m_pFileNameOrBuffer File name to open. 
Predefined GUIDs 
The SWForce SDK includes a header file (Sw_guid.hpp) containing the following predefined GUIDs. 
// 
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// --- SideWinder Effect GUIDs 
// 
GUID Wall 


GUID_RawForce 
GUID_VFXEffect 


// ROM Effects 
GUID_RandomNoise 
GUID_AircraftCarrierTakeOff 
GUID _BasketballDribble 
GUID_CarEngineIdle 
GUID_Chainsawldle 
GUID_ChainsawInAction 
GUID_DieselEngineIdle 
GUID_Jump 

GUID_Land 
GUID_MachineGun 
GUID_Punched 
GUID_RocketLaunch 
GUID_SecretDoor 

GUID SwitchClick 
GUID_WindGust 
GUID_WindShear 
GUID_Pistol 
GUID_Shotgun 
GUID_Laser1l 
GUID_Laser2 
GUID_Laser3 

GUID Laser4 
GUID_Lasers 
GUID_Laser6é 
GUID_OutOfAmmo 
GUID_LightningGun 
GUID_Missile 
GUID_GatlingGun 
GUID_ShortPlasma 
GUID_PlasmaCannon1l 
GUID_PlasmaCannon2 
GUID_Cannon 
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APPENDIX A 


ERROR CODES 


Introduction 


The convention for error codes follows the standard COM and OLE API specification for HRESULT. Each 
interface in IDirectInputDevice2 or IDirectInputEffect returns a value of type HRESULT. HRESULT, or 
“handle to a result" has the same structure as the Win32 error code structure. 


SIR t Facility 
3 130292827126) 16 


The severity code in the 16-bit SCODE and the high order bit in the HRESULT indicates whether the return 

value represents success or failure. If set to zero, SEVERITY_SUCCESS, the value indicates success. If set 

to 1, SEVERITY_ERROR, it indicates failure. In the 16-bit version of the SCODE, the context field is 
"reserved; this field does not exist in the 32-bit version. The R, C, N, and r bits are reserved in both. 


Field Use 

S: (1 bit) Severity field: 0 = Success. The function was successful; it behaved according to 
its proscribed semantics. 
1 =Error. The function failed due to an error condition. 


R, C, N, r (4 bits) Reserved for future use; must be set to zero by present programs 
generating HRESULTs. 
Facility:(11 bits) Indicates which group of status codes this belongs to. 
Code: (16 bits) Describes what actually took place, error or otherwise. 
Valid Error Codes 


The following SideWinder force feedback error codes are valid. Some of them are mapped to 
IDirectInputDevice2 errors. 


Error Code Mapped to Severity Description 
SUCCESS N/A 


Successful method retum 


SFERR_INVALID_OBJECT ERROR Invalid object ID 
SFERR_INVALID_PARAM DIERR_INVALIDPARAM ERROR Invalid method parameter(s) 
SFERR_NO_SUPPORT DIERR_UNSUPPORTED ERROR Method not supported 
SFERR_INVALID_DEVICE DIERR_DEVICENOTREG ERROR Device not found 
SFERR_FFDEVICE_MEMORY DIERR_DEVICEFULL ERROR Out of download RAM 
SFERR_END_OF_LIST STATUS/ End of the list encountered 
WARNING 
SFERR_DEVICE_NACK ERROR Device NACK received 
SFERR_INVALID_STRUCT_SIZE DIERR_INVALIDPARAM ERROR Invalid structure passed 
SFERR_EFFECT_NOT_IN_DEVICE DIERR_NOTDOWNLOADED — ERROR Effect not downloaded 
SFERR_RAW_OUT_DATAEVENT_CREATION ERROR Could not create event 
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Error Code 
SFERR_RAW_OUT_THREAD_CREATION 


SFERR_OUT_OF_FF_MEMORY 
SFERR_SYSTEM_INIT 
SFERR_DRIVER_ERROR 
SFERR_EFFECT_STATUS_BUSY 
SFERR_NON_FF_DEVICE 
SFERR_INVALID_HAL_OBJECT 
SFERR_FF_KERNEL_NOT_FOUND 
SFERR_INVALID_MEMBER_VALUE 
DEERR_SYSTEM_INIT 
SWDEV_ERR_INVALID_ID 
SWDEV_ERR_INVALID_PARAM 
SWDEV_ERR_CHECKSUM 
SWDEV_ERR_TYPE_FULL 
SWDEV_ERR_UNKNOWN_CMD 
SWDEV_ERR_PLAYLIST_FULL 
SWDEV_ERR_PROCESSLIST_FULL 
VFX_ERR_FILE_NOT_FOUND 
VFX_ERR_FILE_OUT_OF_MEMORY 
VFX_ERR_FILE_CANNOT_OPEN 
VFX_ERR_FILE_CANNOT_CLOSE 
VFX_ERR_FILE_CANNOT_READ 
VFX_ERR_FILE_CANNOT_WRITE 
VFX_ERR_FILE_CANNOT_SEEK 
VFX_ERR_FILE_UNKNOWN_ERROR 
VFX_ERR_FILE_BAD_FORMAT 
VFX_ERR_FILE_ACCESS_DENIED 
VFX_ERR_FILE_SHARING_VIOLATION 
VFX_ERR_FILE_NETWORK_ERROR 
VFX_ERR_FILE_TOO_MANY_OPEN_FILES 
VFX_ERR_FILE_INVALID 
VFX_ERR_FILE_END_OF_FILE 


Mapped to 


DIERR_OUTOFMEMORY 


DIERR_INVALIDPARAM 


DIERR_OUTOFMEMORY 


Severi 
ERROR 


ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 


Description 
Could not create a thread 


SWForce system has run out of memory 
Could not create SWForce 

Driver error detected 

Device busy playing effect 
Non-SWForce device, driver not found 
HAL cannot emulate this object 
SWForce Kemel object does not exist. 
Data structure has invalid member value 
SWEffect error: Could not create SWEffect 
Invalid download ID 

Invalid download parameter 

Invalid checksum in COMM packet 

No more RAM space for effect type 
Unrecognized device command 

Play list is full, cannot play any more effects 
Process list is full, cannot download 

File not found 

Out of memory 

Could not open file 

Could not close file 

Could not read file 

Could not write file 

Could not seek file 

Unknown error 

Incompatible file 

File access violation 

File sharing violation 

Network error 

Too many open files 

(nvalid file name 

End of file encountered 
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CONTENTS OF THE SIDEWINDER FORGE 
FEEDBACK SDK 


After installing the SideWinder Force Feedback SDK, the following files and projects reside in your 
c:\SWForce subdirectory. 


Visual Force Factory 


Location: c:\SWForce\sdk\tools\vforce.exe 


Visual Force Factory is a graphical Force Effects editor tool that generates VFX/FRC files. These files 
are used as input for GUID_VFXEffect type of effects created with SWFF_CreateVFXEffectFromX XXX 
functions in the SideWinder Force Feedback Function Library described in Appendix E. Refer to the 
Vforce help file that is accessible through the Windows Start menu. 


Include Files 


Location: C:\SWForce\sdk\inc32 
The include file sw_force.h and sw_guid.hpp are located in this directory. Your projects should point to 
this subdirectory for INCLUDE functionality. 


Binary Files 


Location: C:\SWForce\sdk\bin 


This directory contains copies of the SWForce binaries. 


Sample Programs 


Location: c:\SWForce\sdk\samples\sfresmpl\sfresmpl.exe 


sfresmple.exe is a dialog-based application that shows several examples of using Force Feedback for 


SideWinder. The file swff_lib.cpp is useful as the “wrapper” for simplifying the creation of effects under 
DirectInput Force Feedback API. 


Location: c:\SWForce\sdk\samples\joyforce\joyforce.exe 


This joyforce executable is the classical joytoy.exe program that has been converted to Force Feedback. 


It is a simple application that fires two types of weapon force feedback effects by pressing Trigger button 
and button 2 on your joystick. 


Location: c:\SWForce\sdk\toys\swdemoff\swffdem_.exe 


swffdem_.exe contains several demo programs that let you play and feel different types of effects. It 
includes the following: 


e Tennis Anyone? 
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e Magnet Mania 

e Muddle around the Maze 

e Cruisin’ 

e Cool Effects. 

To start a demo program, left click the image of the program. 


SWFF_LIB SideWinder Force Feedback Library 


The SWForce 1.1 SDK includes a library of C-callable functions that provide functionality to simplify some 
of the DirectInput Force Feedback API methods. The library file swff_lib.epp is in the 
c:\SWForce\sdk\samples\swff_lib subdirectory installed by the SDK setup program. 


SW_Force.h Header file 


SWForce SDK includes a header file (SW_Force.h) that contains predefined constants and function 
prototypes. This file may change to add new features, so make sure you use the latest version of 
SW_Force.h installed by the SDK setup program and located in the c:\SWForce\sdk\ine32 directory. Refer 
to your DirectInput 5.0 documentation for additional DirectX related constants and prototypes. 


78 


APPENDIX C 


IMPLEMENTING AN SWFORCE 
COMPATIBLE GAME USING THE 
“MIDDLE DLL” APPROACH 


Introduction 


The SWForce SDK includes source code which illustrates how to implement force feedback in a game. This 
appendix describes the "Middle DLL" approach and briefly describes the Tiger Shark implementation. 


Using this approach, you can isolate force effects from the game for easier development. 


Method 


Games are typically written in a fashion similar to that shown in the following block diagram. 


| Game 
initialization 


Game Logic/ 
Physics 
Engine/ 
Collision 
Detection 


“Middle DLL“ 


Simulation Data 
Window: 
Missile... 
Terrain... 


initForceFeedback() 
UpdateEfect{) 
ExitForceFeedback() 


The game pipeline consists of the Initialization, Input Engine, Game Logic/Physics Engine/Collision 
Detection, Sound Engine, and Graphics Engine. Events are generated from the Input Engine and are fed to 
the Sound and Graphics engine for rendering and "playback/redraw." 


Force Feedback Events playback are implemented as a separate DLL; the "Middle DLL". Typically, the 
Force Feedback Events are easily triggered along with the Sound and Graphics Events. The DLL is 
responsible for interfacing with the DirectInput Force Feedback API available in DirectX 5. 


Assuming you have already created your Force Effects using the Visual Force Factory editor included in the 
SWForce SDK, the steps are: 
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Implementing an SWForce Compatible Game Using the “Middle DLL” Approach 


Step 1: Initialization 


When your game starts, invoke the Initialization routine. 


// your game init stuff here... 


hRet = InitForceFeedback(hWnd, FALSE); 


The first parameter is the game’s window handle. If you are using DirectInput instead of the WinMM 
JoyGetPosEx call, then this is the same hWnd passed to DirectInput. The second parameter is FALSE to 
indicate that this call is to initialize the DirectInput force feedback objects. If this parameter is TRUE, then 
the request is to re-initialize force effects only. 


Set the second parameter to TRUE (force re-acquire) when calling the function again in a response to a focus 
change message. This is necessary as a focus change will cause previous effects to be cleared from the 
device as it is unacquired. 


Step 2: Modification and Trigger of Events 


The next step is to update the simulation data window. 


Force Feedback Simulation Data Window 

The "Middle DLL" Method uses a data-driven approach to separate the game implementation from the 

details of the underlying Force Feedback subsystem. The game simply defines the different Events that | 
require Force Feedback in a simulation data structure. This represents our "window" from the game events 

to the Force Feedback engine (Middle DLL). 


In Tiger Shark, this interface to the DLL is isolated in the file "winforce.cpp". You will need to include this 
in your game project workspace. Your game application creates the simulation data structure 
TS_SIM_VALUES and fills in the appropriate Event members. The TS_SIM_VALUES structure is below 
and is defined in TS_SFRCE.hpp: 


typedef struct TS SIM VALUES { 
ULONG m_Bytes; 


BOOL bEnableLogFile; 

BOOL bGameAlive; // are we Playing? 

ULONG ulTerrainType; // ABOVE WATER, BELOW_WATER, IN_AIR 
COLLISIONCollision; 

EXPLOSIONExplosion; 


WEAPONFIRE WeaponFire; 
VIBRATION Vibration; 
TIGERSHARK OwnShip; 

} TS_SIM_VALUES, *PTS_SIM_VALUES; 


typedef struct WEAPONFIRE { 
HIT_FIRE Laser; 
HIT_FIRE Cannon; 
HIT_FIRE Missilel; 
HIT_FIRE Missile2; 
HIT_FIRE Missile3; 
HIT_FIRE Torpedol; 
HIT_FIRE Torpedo2; 
HIT_FIRE Torpedo3; 

HIT FIRE OutOfAmmo; 
} WEAPONFIRE , *PWEAPONFIRE; 


typedef struct HIT FIRE { 


BOOL bHit; // TRUE = FIRE 
ULONG ulDirection2D; // 0 - 359 degrees 
ULONG ulGain; // Hit Strength i to 100% | 
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}) HIT_FIRE, *PHIT_FIRE; 


For example, whenever the application detects a joystick trigger button, in response to a Missile launch, it 
will set the Simulation value members: 


TRUE; 
45; 


TS_SimValues.WeaponFire.Missilel.bHit 
TS_SimValues.WeaponFire.ulDirection2D 
TS_SimValues.WeaponFire.ulGain = 50; 
hRet = UpdateEffect(); 


Step 3: Exit 


When your game ends, invoke the exit routine. 


// your game exit stuff here 


hRet = ExitForceFeedback(); 


Exported Functions 


The "Middle DLL" has only the following three exported C-callable functions: 


¢ extern "C" HRESULT InitForceFeedBack(HWND hWnd, BOOL, bReAcquire); 
e extern "C" HRESULT UpdateEffect(); 
e extern "C" HRESULT ExitForceFeedBack(); 


Note: InitForceFeedBack will automatically load the "Middle DLL" and resolve the exported function 
addresses. 


Example Implementation 


Tiger Shark — the game 

Tiger Shark is a fun game with cool graphics and sound. When force feedback is added to the game, a new 
awesome level of play is achieved — Tactile Force Feedback! Force feedback is implemented in Tiger 
Shark using the "Middle DLL" method. Using Visual Force F actory, the force feedback in the current demo 
version of the game was implemented in less than seven hours, with the help and expertise of the game 
developers at n-Space. 


The sources of most interest to the Tshark.dll "Middle DLL" are installed from the CDROM into the 
subdirectory "c:\swforce\sdk\samples\tshark.” 


TS_SFRCE.cpp - TS_SFRCE.cpp is the source for the Initialization, Effect Update, and Exit routines. 


TS_FX.cpp - TS_FX.cpp is the source for the Effects creations. It utilizes mostly GUID_VFXEffects type 
of Effects. You can use Visual Force Factory to edit these Effects. The effects are of the extension "*. FRC". 


Note: The SideWinder Force Feedback Pro supports these type of effects. Other force feedback joysticks 
may not support them, consequently there is no guarantee that Tshark will work with these devices. In such 
cases, you will need to edit this file to change the effect creation from a GUID_VFXEffect type to something 
supported by the other force feedback joystick 


TS_SFRCE.hpp - TS_SFRCE.hpp is the header file to be shared with winforce.cpp. It includes the 
definitions for the data simulation window. 
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WINFORCE.cpp - WINFORCE.cpp should be included in your game project workspace since it contains 
all the necessary functions to interface with the exported functions in the DLL. 


Note: Make sure you have installed SWForce since the project makefile refers to the 
C:\SWFORCE\SDK\INC32 subdirectory for the header files. 


If you have any questions, contact SWFF@microsoft.com. i 


82 


APPENDIX D 


CONVERTING SWFORCE 1.0 GAMES TO 
THE DIRECTINPUT 5.0 FORCE 
FEEDBACK 


Introduction 


This appendix outlines the steps required to convert your SWForce 1.0 game to be SWForce 1.1 and 
compatible with the DirectInput Force Feedback API (DirectX5.0). The APIs and concepts are 
fundamentally the same and most of the functionality is preserved for backward compatibility, although 
some parameters have changed. 


To help with the migration from SWForce 1.0 API to the DirectInput Force Feedback API, we’ve provided a 
library of helper functions which offer familiar SWForce functionality. 


Note: For examples on using the force feedback functions, refer to the sfrcsmpl.cpp source code 
located in C:\SWFORCE\SDK\SAMPLES\SFRCSMPL. 


Conversion Procedure 


If you implemented force feedback in your game using the "Middle DLL" approach, you will find that 
converting to SWForce 1.1 is a breeze. Refer to the example Tiger Shark Middle DLL source code located 
in C:\SWFORCE\SDK\SAMPLES\TSHARK. 


Include the swff_lib.cpp library file in your project workspace. This library is located in 
C:\SWFORCE\SDK\SAMPLES\SWFF _LIB. 


The following steps are followed to help you convert your game to SWForce 1.1: 

Include File 

Change include file from #include "swforce.h" to "sw_force.h". 

Opening a default FF Joystick 

Replace the original OpenDefaultFF Joystick function call with SWFF_OpenDefaultFFJoystickEx(). This 
function requires that an HWND and an HINSTANCE is passed to the function (a quirky requirement for 


DirectInput). For the Tiger Shark Middle DLL example, the HINSTANCE is obtained by the dllEntry in 
TS_Entry.cpp. 


Force and Effect object definitions 

e Replace PSWFORCE with LPDIRECTINPUTDEVICE2 

e Replace PPSWEFFECT with LPDIRECTINPUTEFFECT * 
e Replace pISWForce with pDIDevice 

® Replace EFFECT with DIEFFECT 


¢ Replace ENVELOPE with DIENVELOPE -— Refer to SWForce SideWinder Force Feedback SDK Version 
1.1 Programmer’s Reference 


Parameter modification 
¢ Replace pEffect->SetDirection(..) with SWFF_SetDirection(pEffect, Direction) 


¢ Replace pEffect->SetGain(..) with SWFF_SetGain(pEffect,Direction) 
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Effects Playback and control 

© Replace pEffect->Playback(..) with pEffect->Start(1, 0) 

e Replace pEffect->Playback(PLAY_STOP) with pEffect->Stop() 

¢ Replace pISWForce->PutRawForce(...) with SWFF_PutRawForce(pDIDevice, ppDIEffect, Magnitude, 
dwDirection) 


FRC Effects 
Replace IVFX object functionality with: SWFF_CreateEffectFromVFX(...) 


Note: All Effect resource files of extension *.FRC are fully compatible with SWForce 1.1. There is a 
current limitation to which parameters can be changed. An application can only modify the Direction, Gain, 
and ButtonPlay mask for FRC Effects. If your FRC Effect is composed of a single atomic Effect, you 
should convert it to anon FRC Effect, if you need to control all the DIEFFECT parameters. 


Additional notes/hints: 
e SWForce Gain is +/-100, DirectInput uses +/-10000 
e SWForce Direction is 0 to 359, DirectInput uses 0 to 35999 


¢ SWForce coefficients (K, B, M, F) and Initial Values (VO, AO, AxisCenter) in the Y-Axis are 
North=Positive, South=Negative. DirectInput uses Y-Axis North=Negative, South=Positive. 
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SWFORCE WAVEFORMS, ENVELOPES, 
AND OFFSETS 


For all types of waveforms -- periodic, constant force, and ramp -- there is a way to specify the magnitude of 
the waveform. For example, for periodic waveforms, the magnitude is specified by 
DIPERIODIC.dwMagnitude, and is always half the difference between the maximum and minimum of the 
waveform. Through the envelope structure you can also specify a different (higher or lower) start magnitude 
and end magnitude for all three types of waveforms, as well as specifying the transition times from the 
nominal magnitude to the start and end magnitudes. For two of the waveform types, periodic and ramp, 
there is also a way to specify an offset. Offset is always applied after the envelope. 


Normalized Waveform 


In order to get the resultant waveform, you can think of the magnitude, envelope, and offset being applied to 
a “normalized” waveform. The normalized waveform for any type of waveform is the one with maximum 
amplitude (10,000), no envelope, and no offset. 


Type of waveform Normalized Parameters 

Periodic DIPERIODIC.dwMagnitude = 10,000 DIPERIODIC.lOffset = 0 
Constant Force DICONSTANTFORCE.dwMagnitude = 10,000 

Ramp DIRAMPFORCE.|Start = +/-10,000 DIRAMPFORCE.lEnd = -/+10,000 


Determining the Resultant Waveform 


In order to determine the resultant waveform, each point along the waveform of the normalized. function is 
scaled by a time-dependent function, which is determined by the magnitude and envelope. Each point is 
then offset by a certain amount. 


Sealing Function | 
10,000 


Normalized & ae ( Resultant | 
a annem - a 
( Waveform 7 a Waveform F 


| Offset Terms. 
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The Scaling Function 


The scaling function is basically the envelope that is applied to the normalized waveform. Its shape is shown 
below. The attack level and fade level can each be higher or lower than the sustain level. 


AttackTime FadeTime 
—_—— 
* pe -Suustain- bevel ch dese 
AttackLevel a dl 
. FadeLevel 
Figure 1. 


For all types of waveforms: 


AttackTime = DIENVELOPE.dwAttackTime 
FadeTime = DIENVELOPE.dwFadeTime 
AttackLevel = DIENVELOPE.dwAttackLevel 
FadeLevel = DIENVELOPE.dwFadeLevel 


SustainLevel differs depending on the type of waveform: 


Type of Waveform Sustain Level 

Periodic DIPERIODIC.dwMagnitude 

Constant Force DICONSTANTFORCE.dwMagnitude 

Ramp Abs(DIRAMPFORCE.|Start - DIRAMPFORCE.1|End)/2 
The Offset Term 


It is only after the envelope is applied that any offset is applied. Applying the offset after the scaling means 
that the basic shape of the resultant waveform does not depend on the offset, it is only shifted. The value of 
the offset depends on the type of effect. 


Type of Waveform Offset 

Periodic DIPERIODIC.dwMagnitude 

Constant Force None 

Ramp (DIRAMPFORCE. Start + DIRAMPFORCE.lEnd)/2. 


Example 1 — Periodic Effect 


A sawtooth with the following parameters appears as shown in the following illustrated steps: 


GUID_SAWTOOTHUP 

DIEFFECT.dwDuration = 1,000,000 (1 sec) 
DIPERIODIC.dwPeriod = 100,000 (0.1 sec or 10Hz) 
DIPERIODIC.dwMagnitude = 5000 (50%) 
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DIPERIODIC.1Offset = 1000 (10%) 
DIENVELOPE.dwAttackLevel = 8000 (80%) 
DIENVELOPE.dwAttackTime = 300,000 (0.3 sec) 
DIENVELOPE.dwFadeLevel = 1000 (10%) 
DIENVELOPE.dwFadeTime = 400,000 (0.4 sec) 


Step 1: Normalized Waveform 
Start out with the normalized sawtooth. It is a maximum amplitude sawtooth with no offset and no envelope. 


GUID_SAWTOOTHUP 

DIEFFECT.dwDuration = 1,000,000 (1 sec) 
DIPERIODIC.dwPeriod = 100,000 (0.1 sec or 10Hz) 
DIPERIODIC.dwMagnitude = 10000 (100%) 
DIPERIODIC.lOffset = 0 (0%) 

&DIENVELOPE = NULL 


Step 2: Scaling Function (envelope) 
Referring to Figure | definitions, find the time-dependent scaling function. 


AttackTime = DIENVELOPE.dwAttackTime = 300,000 
AttackLevel = DIENVELOPE.dwAttackLevel = 8000 
SustainLevel = DIPERIODIC.dwMagnitude = 5000 
FadeTime = DIENVELOPE.dwFadeTime = 400,000 
FadeLevel = DIENVELOPE.dwFadeLevel 


Step 3: Apply the scaling function to the normalized waveform 


To apply the envelope, for each point on the curve of the normalized waveform, multiply it times the scaling 
function (divided by 10,000). 
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GUID_SAWTOOTHUP 

DIEFFECT.dwDuration = 1,000,000 (1 sec) 
DIPERIODIC.dwPeriod = 100,000 (0.1 sec or 10Hz) 
DIPERIODIC.dwMagnitude = 5000 (50%) 
DIPERIODIC.lOffset = 0 (0%) 
DIENVELOPE.dwAttackLevel = 8000 (80%) 
DIENVELOPE.dwAttackTime = 300,000 (0.3 sec) 
DIENVELOPE.dwFadeLevel = 1000 10%) 
DIENVELOPE.dwFadeTime = 400,000 (0.4 sec) 


The shape of the resultant waveform has been determined, now just apply the offset. 


Step 4: Apply the offset 


To apply the offset, just shift each point in step 3 by the offset amount. In this case, the waveform is shifted 
up by DIPERIODIC.1Offset = 1000 units providing the final resultant waveform. 


GUID_SAWTOOTHUP 

DIEFFECT.dwDuration = 1,000,000 1 sec) 
DIPERIODIC.dwPeriod = 100,000 (0.1 sec or 10Hz) 
DIPERIODIC.dwMagnitude = 5000 (50%) 
DIPERIODIC.lOffset = 1000 (10%) 
DIENVELOPE.dwAttackLevel = 8000 (80%) 
DIENVELOPE.dwAttackTime = 300,000 (0.3 sec) 
DIENVELOPE.dwFadeLevel = 1000 (10%) 
DIENVELOPE.dwFadeTime = 400,000 (0.4 sec) 


Example 2 — Constant Force Effect 


A constant force effect with the following parameters appears as shown in the following illustrated steps: 


GUID_CONSTANTFORCE 
DIEFFECT.dwDuration = 1,000,000 (1 sec) 
DICONSTANTFORCE.dwMagnitude = 5000 (50%) 
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DIENVELOPE.dwAttackLevel = 8000 (80%) 
DIENVELOPE.dwaAttackTime = 300,000 (0.3 sec) 
DIENVELOPE.dwFadeLevel = 1000 (10%) 
DIENVELOPE.dwFadeTime = 400,000 (0.4 sec) 


Step 1: Normalized Waveform 
Start out with the normalized constant; a maximum amplitude constant force with no envelope. 


GUID_CONSTANTFORCE 

DIEFFECT.dwDuration = 1,000,000 (1 sec) 
DICONSTANTFORCE.dwMagnitude = 10,000 (100%) 
&DIENVELOPE = NULL 


Step 2: Scaling Function (envelope) 
Referring to figure for definitions, find the time-dependent scaling function. 


AttackTime = DIENVELOPE.dwAttackTime = 300,000 
AttackLevel = DIENVELOPE.dwAttackLevel = 8000 
SustainLevel = DICONSTANTFORCE.dwMagnitude = 5000 
FadeTime = DIENVELOPE.dwFadeTime = 400,000 
FadeLevel = DIENVELOPE.dwFadeLevel = 1000 


Step 3: Apply the scaling function to the normalized waveform 


To apply the envelope, for each point on the curve of the normalized waveform, multiply it times the scaling 
function (divided by 10,000). The shape of the resultant waveform has been determined. At this point, since 
a constant force has no offset associated with it, it is finished. Note that the resultant waveform will follow 
the envelope shape exactly; that is, they are identical. 
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GUID_CONSTANTFORCE 
DIEFFECT.dwDuration = 1,000,000 (1 sec) 
DICONSTANTFORCE.dwMagnitude = 5000 (50%) 
DIENVELOPE.dwAttackLevel = 8000 (80%) 
DIENVELOPE.dwAttackTime = 300,000 (0.3 sec) 
DIENVELOPE.dwFadeLevel = 1000 (10%) 
DIENVELOPE.dwFadeTime = 400,000 (0.4 sec) 


Example 3 — Ramp Effect 


A ramp effect with the following parameters appears as shown in the following illustrated steps: 


GUID_RAMP 

DIEFFECT.dwDuration = 1,000,000 (1 sec) 
DIRAMPFORCE.|Start = -2000 (-20%) 
DIRAMPFORCE.IEnd = 8000 (80%) 
DIENVELOPE.dwAttackLevel = 8000 (80%) 
DIENVELOPE.dwAttackTime = 300,000 (0.3 sec) 
DIENVELOPE.dwFadeLevel = 1000 (10%) 
DIENVELOPE.dwFadeTime = 400,000 (0.4 sec) 


Note that unlike other types of waveforms, a ramp does not specify its magnitude and offset explicitly. 
However, they can be inferred from the DIRAMPFORCE structure. For this example: 


Mapnitude = abs(DIRAMPFORCE.|Start - DIRAMPFORCE.lEnd)/2 = 5000 
Offset = (DIRAMPFORCE. Start + DIRAMPFORCE.IEnd)/2 = 3000 


Step 1: Normalized Waveform 


Start out with the normalized ramp. It is the ramp with the most negative possible start and most positive 
possible end. 


GUID_RAMP 
DIEFFECT.dwDuration = 1,000,000 (1 sec) 
DIRAMPFORCE. Start = -10,000 (-100%) 
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DIRAMPFORCE.lEnd = 10,000 (100%) 
&DIENVELOPE = NULL 


Step 2: Scaling Function (envelope) 


Referring to Figure | for definitions, find the time-dependent scaling function. 


soca linda waits teamed ice eda oe B. 
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AttackTime = DIENVELOPE.dwAttackTime = 300,000 

AttackLevel = DIENVELOPE.dwAttackLevel = 8000 

SustainLevel = abs(DIRAMPFORCE. Start - DIRAMPFORCE.lEnd)/2= 5000 
FadeTime = DIENVELOPE.dwFadeTime = 400,000 

FadeLevel = DIENVELOPE.dwFadeLevel = 100,000 


Step 3: Apply the scaling function to the normalized waveform 


To apply the envelope, for each point on the curve of the normalized waveform, multiply it times the scaling 
function (divided by 10,000). The shape of the resultant waveform has been determined. 


GUID_RAMP 

DIEFFECT.dwDuration = 1,000,000 (1 sec) 
DIRAMPFORCE. Start = -5000 (-50%) 
DIRAMPFORCE.lEnd = 5000 (50%) 
DIENVELOPE.dwAttackLevel = 8000 (80%) 
DIENVELOPE.dwAttackTime = 300,000 (0.3 sec) 
DIENVELOPE.dwFadeLevel = 1000 (10%) 
DIENVELOPE.dwFadeTime = 400,000 (0.4 sec) 


Step 4: Apply the offset 


To apply the offset, just shift each point in step 3 by the offset amount. In the case of a ramp, the offset can 
be calculated from the DIRAMPFORCE structure. Offset = (DIRAMPFORCE Start + 
DIRAMPFORCE.IEnd)/2 = 3000. The waveform is shifted up by 3000 units. That gives us the final 
resultant waveform. 
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GUID_RAMP 

DIEFFECT.dwDuration = 1,000,000 (1 sec) 
DIRAMPFORCE.|Start = -2000 (-20%) 
DIRAMPFORCE.|End = 8000 (80%) 
DIENVELOPE.dwAttackLevel = 8000 (80%) 
DIENVELOPE.dwAttackTime = 300,000 (0.3 sec) 
DIENVELOPE.dwFadeLevel = 1000 (10%) 
DIENVELOPE.dwFadeTime = 400,000 (0.4 sec) 


Example 4 — Ramp Effect | 


A ramp effect with the following parameters appears as shown in the following illustrated steps: 


GUID_RAMPEFFECT 

DIEFFECT.dwDuration = 1,000,000 (1 sec) 
DI_LRAMPFORCE.|Start = 0 (0%) 
DI_RAMPFORCE.lEnd = 10,000 (100%) 
DIENVELOPE.dwAttackLevel =0 (0%) 
DIENVELOPE.dwAttackTime = 100,000 (.1 sec) 
DIENVELOPE.dwFadeLevel = 0 (0%) 
DIENVELOPE.dwFadeTime = 100,000 1 sec) 


Note that unlike other types of waveforms, a ramp does not specify its magnitude and offset explicitly. 
However, they can be inferred from the DIRAMPFORCE structure. For this example: 


Magnitude = abs(DIRAMPFORCE. Start - DIRAMPFORCE. lEnd)/2 = 5000 
Offset = (DIRAMPFORCE.IStart + DIRAMPFORCE.lEnd)/2 = 5000 


Step 1: Normalized Waveform 


Start out with the normalized ramp; the ramp with the most negative possible start and most positive possible 
end. 


{bme AppCfig13.bmp} 
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GUID_RAMP 

DIEFFECT.dwDuration = 1,000,000 (1 sec) 
DIRAMPFORCE.|Start = -10,000 (-100%) 
DIRAMPFORCE.lEnd = 10,000 (100%) 
&DIENVELOPE = NULL 


Step 2: Scaling Function (envelope) 
Referring to Figure 1 for definitions, find the time-dependent scaling function. 


AttackTime = DIENVELOPE.dwAttackTime = 100,000 

AttackLevel = DIENVELOPE.dwAttackLevel = 0 

SustainLevel = abs(DIRAMPFORCE.|Start - DIRAMPFORCE.lEnd)/2= 5000 
FadeTime = DIENVELOPE.dwFadeTime = 100,000 

FadeLevel = DIENVELOPE.dwFadeLevel = 0 


Step 3: Apply the scaling function to the normalized waveform 


To apply the envelope, for each point on the curve of the normalized waveform, multiply it times the scaling 
function (divided by 10,000). The shape of the resultant waveform has been determined. Now just apply the 
offset. 
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GUID_RAMP 

DIEFFECT.dwDuration = 1,000,000 (1 sec) 
DIRAMPFORCE. Start = -5000 (-50%) 
DIRAMPFORCE.lEnd = 5000 (50%) 
DIENVELOPE.dwAttackLevel = 0 (0%) 
DIENVELOPE.dwAttackTime = 100,000 (0.1 sec) 
DIENVELOPE.dwFadeLevel = 0 (0%) 
DIENVELOPE.dwFadeTime = 100,000 (0.1 sec) 


Step 4: Apply the offset 


To apply the offset, just shift each point in step 3 by the offset amount. In the case of a ramp, the offset can 
be calculated from the DIRAMPFORCE structure. Offset = (DIRAMPFORCE.|Start + 
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DIRAMPFORCE.lEnd)/2 = 5000. The waveform is shifted up by 5000 units. That gives us the final 
resultant waveform. 


GUID_RAMP 

DIEFFECT.dwDuration = 1,000,000 (1 sec) 
DIRAMPFORCE.|Start = 0 (0%) 
DIRAMPFORCE.lEnd = 10000 (100%) 
DIENVELOPE.dwAttackLevel = 0 (0%) 
DIENVELOPE.dwAttackTime = 100,000 (0.1 sec) 
DIENVELOPE.dwFadeLevel = 0 10%) 
DIENVELOPE.dwFadeTime = 100,000 (0.1 sec) 
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PROGRAMMING CONSIDERATIONS 


Introduction 


This appendix contains information which may be helpful when implementing force feedback with the 
SWForce SDK. 


MIDI Channel Assignment 


Side Winder Force Feedback Pro uses Digital Overdrive for position input data and uses the MIDI lines for 
the output of force effect data. The default MIDI channel for force effect communication is channel 5. 


Windows multimedia MIDI channels are defined as numbered 1 through 16, so the default channel used 
for force data is actually channel 6. In order to minimize any potential data conflicts your application 
should, if possible, avoid the use of MIDI channel 6. 


Opening the Joystick and MIDI Line Conflicts 


The Side Winder Force Feedback Pro communicates via the MIDI portion of the sound card. Playing MIDI 
music while initially opening the joystick may interfere with joystick-to-computer communication. To 
avoid possible interference in communication, it is recommended that the application refrain from playing 
MIDI music until after the joystick has been successfully opened. 


Using the Correct Header Files 


The code samples included with the SWForce SDK (sfresmpl, joyforce, and tshark) are supplied with their 
own copy of dinput.h and dinput.lib. This allows you to install the DX SDK and any location on your 
system, but still allow the samples to compile. For your own development purposes, you should use the 
dinput.h and dinput.lib provided with the DX SDK. 


Working with FRC Files 


When you use the Visual Force Factory to create and save one or more force effects, you create an FRC 
file. FRC files provide a way to encapsulate the data needed to create a force effect. By using the Visual 
Force Factory to create FRC files, you can separate the task of authoring effects from that of game 
development. The code in the game can simply create an effect object from an FRC file. The FRC file 
allows the effect to be changed without recompiling. 


VEXEffect Types from Visual Force Factory Files 


The SideWinder driver and hardware directly support FRC files using the GUID_VFXEffect type effect. 
This type of effect also allows you to treat an FRC file containing multiple sub-effects as a single effect. 


SWForce contains the following wrapper functions, included in the SWForce library, to simplify creation 
of GUID_VFXEffect type effects: SWFF_CreateVFXEffectFromFile, 
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SWFF_CreateVFXEffectFromFileEx, SWFF_CreateVFXEffectFromBuffer, and 
SWFF_CreateVFXEffectFromBufferEx. 


These functions make calls to the CreateEffect method of the IDirectInputDevice2 interface. 


DirectInput-compatible Effects from Visual Force Factory Files 


The SWForce SDK includes VFX.DLL which allows you to create effects, from FRC files, for force 
feedback devices that are DirectInput5.0-compatible. VFX.DLL contains functions which read the 
contents of an FRC file and make equivalent calls into DirectInput5.0. However, because other devices do 
not support VFX effects directly, multiple effects within FRC files cannot be treated as a single effect, as 
they can with when using the GUID_VFXEffect type effect. 


The following functions are included in the library to simplify creation of effects using FRC files in 
conjunction with VFX DLL: SWFF_CreateDIEffectFromFile, SWFF_CreateDIEffectFromFileEx, 
SWFF_CreateDIEffectFromBuffer, and SWFF_CreateDIEffectFromBufferEx. 


These functions make calls to the CreateEffectFromFile and CreateEffectFromBuffer methods of the 
IVFX interface contained in VFX.DLL. 


If you choose to use the IVFX interface, you’!l need to install VFX DLL along with your game. The 
library function SWFF_Register VFX provides registry entries you need to set during installation of your 
game. 


Including FRC Files Into VFX Files 


FRC files can be included in your .rc file as binary resources. Visual Force Factory simplifies the process 
by creating resource compiler-compatible VFX files. A VFX file is a text file containing a list of FRC files 
and has the format shown in the following example: 


IDF_JUMP1 FORCE DISCARDABLE “jumpl.fre” 
IDF_JUMP2 FORCE DISCARDABLE “jump2.fre” 


To create a VFX file, which contains a list of all the FRC files you want to include as resources, do the 
following: 


1 Start Visual Force Factory, select File/New and then choosing Force Resource Script from the list box. 


2 Select Insert/Existing Effect, then select the FRC file you want to include in the resource script. The file 
should be in the same directory as your .rc file. 


3 Repeat step 2 for all the files you wish included in the resource. 
4 Save the .vfx file in the same directory as your .rc file. For example, scriptl.vfx. 


To include the .vfx file in your .rc file, open the .rc file as a text file and insert the line #include 
“scriptl.vfx” (where script] .vfx is the name of your VFX file). 


When you compile your executable, the FRC files will be included as binary resources. Use the wrapper 
function SWFF_CreateVFXEffectFromBuffer(...) to create effects using the resource. An example of how 
to use this function follows. 


HRSRC hResInfo = FindResource (NULL, "“IDF_FOO", "FORCE"); 

DWORD dwBytes = SizeofResource(NULL, hResInfo); 

HGLOBAL hRsre = LoadResource (NULL, hResInfo); 

PVOID pBuffer = LockResource (hRsrc) ; 
SWEF_CreateVFxEffectFromBuffer(pDIDevice, &pDIEffect, pBuffer, dwBytes); 
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Handling Process Activation Changes 
The following information may be helpful when handling changes in force feedback process activation. 
Use DISCL_EXCLUSIVE | DISCL_FOREGROUND. 


The use of DISCL_EXCLUSIVE | DISCL_FOREGROUND in IDirectInputDevice::SetCooperativeLevel 
causes the force feedback device to be automatically un-acquired upon process deactivation. This prevents 
the user from getting forces to the force feedback device when operating non-force feedback applications. 
Other force feedback applications can still acquire the device. If you use the SWForce library function, 
SWFF_OpenDefaultFF Joystick, this is done by default. 


Reacquire the device in response toa WM_ACTIVATE message. 


If you don't reacquire the device up on WM_ACTIVATE, your game will lose force feedback whenever a 
task-switch has occurs (see "Checking for Lost Joystick Input" topic in DirectInput online help). You also 
need to restart any effects which should be playing at the time of the task-switch. 


Do not prevent task-switching away from your game by means of Alt+Tab. 


Be sure to allow your game to task-switch. Enabling your application to task-switch allows you to use the 
Visual Force Factory to edit any FRC files you may be using on-the-fly. 


Note: This feature does not work with IVFX methods, only VFXEffects. 
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